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OS-9 
Level Two 


Operating 
System 


OS-9 Level Two Operating System (software): 
© 1986, Microware Systems Corporation 
Licensed to Tandy Corporation. 

All Rights Reserved. 


All portions of this software are copyrighted and are the 
proprietary and trade secret information of Tandy 
Corporation and/or its licensor. Use, reproduction or 
publication of any portion of this material without the 
prior written authorization by Tandy Corporation is 
strictly prohibited. 


OS-9 Level Two Operating System (manual): 
© 1986, Tandy Corporation. 
All Rights Reserved. 


Reproduction or use of any portion of this manual, without 
express written permission from Tandy Corporation and/or 
its licensor, is prohibited. While reasonable efforts have 
been made in the preparation of this manual to assure its 
accuracy, Tandy Corporation assumes no liability 
resulting from any errors in or omissions from this 
manual, or from the use of the information contained 
herein. 


Tandy is a registered trademark of Tandy Corporation. 
OS-9 is a trademark of Microware Systems Corporation. 


BASICO9 is a trademark of Microware Systems 
Corporation and Motorola, Inc. 
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TERMS AND CONDITIONS OF SALE AND LICENSE OF TANDY COMPUTER EQUIPMENT AND 
SOFTWARE PURCHASED FROM RADIO SHACK COMPANY-OWNED COMPUTER CENTERS, RETAIL 
STORES AND RADIO SHACK FRANCHISEES OR DEALERS AT THEIR AUTHORIZED LOCATIONS 


USA LIMITED WARRANTY 
CUSTOMER OBLIGATIONS 


A. CUSTOMER assumes full responsibility that this computer hardware pee (the ‘‘Equipment’’), and any 
copies of software included with the Equipment or licensed separately (the ‘‘Software’’) meets the specifications, 
capacity, capabilities, versatility, and other requirements of CUSTOMER. 

B. CUSTOMER assumes full responsibility for the condition and effectiveness of the operating environment in which 
the Equipment and Software are to function, and for its installation. 

LIMITED WARRANTIES AND CONDITIONS OF SALE 

A. For a period of ninety (90) calendar days from the date of the Radio Shack sales document received upon 
purchase of the Equipment. RADIO SHACK warrants to the original CUSTOMER that the Equipment and the 
medium upon which the Software is stored is free from manufacturing defects. This warranty is only applicable 
to purchases of Tandy Equipment by the original customer from Radio Shack company-owned computer 
centers, retail stores, and Radio Shack franchisees and dealers at their authorized locations. The warranty is 
void if the Equipment or Software has been subjected to improper or abnormal use. If a manufacturing defect is 
discovered during the stated warranty period, the defective Equipment must be returned to a Radio Shack 
Computer Center, a Radio Shack retail store, a participating Radio Shack franchisee or a ey Radio Shack 
dealer for repair, along with a copy of the sales document or lease agreement. The original CUSTOMER'S sole and 
exclusive remedy in the event of a defect is limited to the correction of the defect by repair, replacement, or 
refund of the purchase price, at RADIO SHACK’S election and sole expense. RADIO SHACK has no obligation to 
replace or repair expendable items. 

RADIO SHACK makes no warranty as to the design, capability, capacity, or suitability for use of the Software, 
except as Bove in this paragraph. Software is licensed on an “‘AS IS’’ basis, without warranty. The original 
CUSTOMER’S exclusive remedy, in the event of a Software manufacturing defect, is its repair or replacement 
within thirty (30) calendar days of the date of the Radio Shack sales document received upon license of the 
Software. The defective Software shall be returned to a Radio Shack Computer Center, a Radio Shack retail store, 
a participating Radio Shack franchisee or Radio Shack dealer along with the sales document. 

Except as provided herein no clea agent, franchisee, dealer or other person is authorized to give any 
warranties of any nature on behalf of RADIO SHACK. 

EXCEPT AS PROVIDED HEREIN, RADIO SHACK MAKES NO EXPRESS WARRANTIES, AND ANY IMPLIED 
WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE IS LIMITED IN ITS DURATION 
TO THE DURATION OF THE WRITTEN LIMITED WARRANTIES SET FORTH HEREIN. 

Some states do not allow limitations on how long an implied warranty lasts, so the above limitation(s) may not 
apply to CUSTOMER. 

. LIMITATION OF LIABILITY 

A. EXCEPT AS PROVIDED HEREIN, RADIO SHACK SHALL HAVE NO LIABILITY OR RESPONSIBILITY TO CUSTOMER 

OR ANY OTHER PERSON OR ENTITY WITH RESPECT TO ANY LIABILITY, LOSS OR DAMAGE CAUSED OR 

ALLEGED TO BE CAUSED DIRECTLY OR INDIRECTLY BY ‘EQUIPMENT’ OR “SOFTWARE’’ SOLD, LEASED, 

LICENSED OR FURNISHED BY RADIO SHACK, INCLUDING, BUT NOT LIMITED TO, ANY INTERRUPTION OF 

SERVICE, LOSS OF BUSINESS OR ANTICIPATORY PROFITS OR CONSEQUENTIAL DAMAGES RESULTING FROM 

THE USE OR OPERATION OF THE “EQUIPMENT” OR “SOFTWARE.” IN NO EVENT SHALL RADIO SHACK BE 

LIABLE FOR LOSS OF PROFITS, OR ANY INDIRECT, SPECIAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF 

ANY BREACH OF THIS WARRANTY OR IN ANY MANNER ARISING OUT OF OR CONNECTED WITH THE SALE, 

LEASE, LICENSE, USE OR ANTICIPATED USE OF THE “EQUIPMENT” OR “SOFTWARE.” 

NOTWITHSTANDING THE ABOVE LIMITATIONS AND WARRANTIES, RADIO SHACK’S LIABILITY HEREUNDER FOR 

DAMAGES INCURRED BY CUSTOMER OR OTHERS SHALL NOT EXCEED THE AMOUNT PAID BY CUSTOMER FOR 

THE PARTICULAR ‘‘EQUIPMENT” OR ‘‘SOFTWARE”’ INVOLVED. a 

dearth SHACK shall not be liable for any damages caused by delay in delivering or furnishing Equipment and/or 

oftware. 

No action arising out of any claimed breach of this Warranty or transactions under this Warranty may be brought 

more than two 00) En after the cause of action has accrued or more than four (4) years after the date of the 

Radio Shack sales document for the Equipment or Software, whichever first occurs. 

Some states do not allow the limitation or exclusion of incidental or consequential damages, so the above 

limitation(s) or exclusion(s) may not apply to CUSTOMER. 


. SOFTWARE LICENSE 


RADIO SHACK grants to CUSTOMER a non-exclusive, paid-up license to use the TANDY Software on one computer, 

subject to the following provisions: 

A. Except as otherwise provided in this Software License, applicable copyright laws shall apply to the Software. 
Title to the medium on which the Software is recorded (cassette and/or diskette) or stored (ROM) is transferred to 
CUSTOMER, but not title to the Software. 
CUSTOMER may use Software on a multiuser or network system only if either, the Software is expressly labeled 
to be for use on a multiuser or network system, or one copy of this software is purchased for each node or 
terminal on which Software is to be used simultaneously. 
CUSTOMER shall not use, make, manufacture, or reproduce copies of Software except for use on one computer 
hl is specifically provided in this Software License. Customer is expressly prohibited from disassembling the 

oftware. 

CUSTOMER is permitted to make additional copies of the Software only for backup or archival purposes or if 
additional copies are required in the operation of one computer with the Software, but only to the extent the 
Software allows a backup copy to be made. However, for TRSDOS Software, CUSTOMER is permitted to make a 
limited number of additional copies for CUSTOMER’S own use. 
CUSTOMER may resell or distribute unmodified copies of the Software provided CUSTOMER has purchased one 
copy of the Software for each one sold or distributed. The provisions of this Software License shall also be 
applicable to third parties receiving copies of the Software from CUSTOMER. 

G. All copyright notices shall be retained on all copies of the Software. 

APPLICABILITY OF WARRANTY 

A. The terms and conditions of this Warranty are applicable as between RADIO SHACK and CUSTOMER to either a 
sale of the Equipment and/or Software License to CUSTOMER or to a transaction whereby Radio Shack sells or 
conveys such ergs to a third party for lease to CUSTOMER. 

B. The limitations of liability and Warranty provisions herein shall inure to the benefit of RADIO SHACK, the author, 
owner and or licensor of the Software and any manufacturer of the Equipment sold by Radio Shack. 


. STATE LAW RIGHTS 


The warranties granted herein give the original CUSTOMER specific legal rights, and the original CUSTOMER may 
have other rights which vary from state to state. 4/87 
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- Getting Started 
With 
OS-9 


About This Manual 


Using Your OS-9 Handbook 


If you feel that starting a new computer operating system is a 
“scary business,” relax. This handbook is designed to put you at 
ease when using OS-9. It is divided into two parts—each part has 
a different purpose. 


What is in Part 1 


“Part 1” of this handbook is designed to show you, step by step, 
how to set up and use your computer with OS-9. Follow the steps 
as they are described, and OS-9 is your obedient servant. The few 
instructions in “Part 1” are all that many OS-9 users ever need. 


What is in Part 2 


“Part 2” is for the more adventurous. OS-9 has an extensive rep- 
ertoire of commands and functions to create and manage data and 
to make use of peripherals (devices you can connect to your com- 
puter, such as disk drives and printers). If you want to learn more 
about the operating system, and if you like to explore, “Part 2” is 
for you. You learn other useful OS-9 commands that prepare you 
to make use of all the functions and commands described in 
OS-9 Commands. 
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What You Need to Know 
About OS-9 


Chapter 1 


What is an Operating System? 


OS-9 is a disk Operating System (that’s what OS stands for). An 
operating system is a group of programs acting as a message 
center and an interpreter. Using your instructions, an operating 
system manages the computer’s working circuits. 


In fact, thinking of OS-9 as your computer manager is helpful. 
The boss (that’s you) gives orders. OS-9 (the manager) sees they 
get done. 


To operate OS-9 you need at least one floppy disk drive attached 
to your computer. OS-9 is originally configured to recognize two 
floppy disk drives. Later, this handbook describes how to let OS-9 
know if you have more than two floppy disk drives, or if you have 
other hardware (printers, modems, hard disks, and so on) you 
want it to recognize. 


Instructing Your Operating System 


You give your commands to OS-9 by typing them. Because OS-9 
does exactly (and only) what you tell it, your entries must be pre- 
cise and have perfect syntax (spelling and form). You must also be 
sure to give OS-9 every detail it needs to perform a task. 


For instance, if you told your office manager to, “Make a phone 
call,” what can the manager do? Obviously, not much that is 
helpful to you. The manager must know who to call, the phone 
number, and what to say. OS-9 is the same. It must have all the 
details before it can carry out your commands properly. 


To show you how to instruct your operating system, the hand- 
book asks you to type characters, words, and lines on your key- 
board. When you do, you are issuing commands to OS-9. 
Technically, a command is only one word that describes the action 
you want OS-9 to perform. A command line is a command with all 
of its qualifiers. 


In this manual, command lines usually contain words in boxes, 
such as [ENTER]. These indicate keys that you press. 


The manual also asks you to press key sequences. For instance, 
when asked to press (Cc), hold down the key marked CTRL, 
and while holding down (CTRL), press (C]. 


Getting Started With OS-9 


Characters that are not in boxes are typed individually. For 
instance, if you are asked to type the command line format /d@ 
(ENTER ], press each key individually ((F) (0) (R) (4) C10 Ww 
(ENTER }). 


If you make a mistake while typing, use to move back to the 
error. Then retype that portion of the line. 


Using Application Programs and 
Computer Languages 


A computer application is a program designed to accomplish spe- 
cific tasks. There are application programs to help you write let- 
ters or documents (word processors), keep a mailing list (data 
managers), and keep financial records (accounting packages). 
There are also programs to help you study for a test, play a game, 
play music, draw a picture, and much more. 


Such application programs usually require that you use OS-9 to 
start your computer. A few application programs let you start 
directly from the application diskette. Different programs can 
require different procedures, and you should check your applica- 
tion program’s documentation for specific instructions. 


Application programs have special screen displays and menus to 
instruct you, or that require you to perform a particular action, 
such as press a key. When you are operating from an application 
program, that program passes your instructions to OS-9. OS-9 
manages the computer’s operations in the background, and its 
functions are invisible to you. 


You can also use computer languages to write your own applica- 
tion programs. BASIC is a language. If you read the Color 
Computer Disk System manual, you already know a bit about it. 
There are languages you can purchase to use with OS-9 to cre- 
ate programs, such as assembly language, Pascal, C, and 
BASIC-09. 


Like application programs, each language has its own startup 
method. The manuals that come with the languages tell you how 
to get them running on your Color Computer 3. 
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Using Peripherals 


OS-9 lets you control much more than your computer’s opera- 
tions. It also gives you control over other hardware devices such as 
disk drives, a printer, modems, windows, other terminals, and so 
on. 


Each device has a “System Name,” an abbreviation preceded by a 
slash (/). OS-9 can only recognize a device if you type its name 
exactly as shown below. See Chapter 7, “Customizing Your 
System” for information on how to tell OS-9 what devices you 
want it to handle. 


System 
Name Description 
/P A printer connected through your computer’s RS- 


232 port. The RS-232 port is a serial port, and 
you must have a printer with a serial connection, 
such as the Radio Shack® DMP 430. 


/T1 A data terminal or another computer acting as a 
terminal, connected through the RS-232 port of 
your computer. If you are using another computer 
as a terminal, it must run a terminal program 
that makes it perform as a terminal. 


riz Another data terminal or another computer act- 
ing as a terminal, connected to an optional RS- 
232 communications pak in a Multi-Pak Inter- 
face. If you are using another computer as a ter- 
minal, it must run a terminal program that 
makes it perform as a terminal. 


/T3 Another data terminal or another computer act- 
ing as a terminal, connected to the optional RS- 
232 communications pak in a Multi-Pak 
Interface. If you are using another computer as a 
terminal, it must run a terminal program that 
makes it perform as a terminal. 


/M1 A modem using an optional 300-baud modem pak 
in the optional Multi-Pak Interface. A modem 
allows you to communicate with other computers 
either directly or over phone lines. 
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System 
Name 


/M2 


/DO 
/D1 


/W, /W1, 
/W2, /W3 
/W4, /W5 
/W6, /W7 


Description 

Another modem using an optional 300-baud 
modem pak in the optional Multi-Pak Interface. 
A floppy disk drive. 

Another floppy disk drive 


Windows that you can establish on your OS-9 
system. You use to page among windows 
you create. See “Using Windows” in Chapter 7 
and OS-9 Windowing System Owner’s Manual for 
information on creating windows. 


Why Use OS-9? 


You now know that OS-9 is an operating system for your Color 
Computer. You might also have heard that, in the world of com- 
puter operating systems, OS-9 is a leader. Perhaps that is why you 
bought it. OS-9 stands out for several reasons. Some of its strong 


points are: 


e File managing capabilities. 


@ Multi-user features. With OS-9, more than one person can 
use the same computer at the same time. 


@ Multi-tasking. OS-9 can handle several jobs at the same 


time. 


@ Window functions that let you divide your display screens 
into sections in which you can have one or more opera- 
tions running, all at the same time. 


@ Input/Output capabilities. OS-9 can communicate with 
TVs and monitors, disk drives, printers, and other 
computers. 


@ A sophisticated repertoire of commands. 


® Sophisticated programming languages. 


If you are not familiar with such terms as files, multi-user, multi- 
tasking, and commands, don’t worry. The handbook explains these 
terms and more. 
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Programmers like OS-9 because of its powerful features. It lets 
them show off all of their skills. As a result, another OS-9 fea- 
ture is the wide range of excellent programs that you can use 
with the system. 


How Much Do You Need to Know 
About OS-9? 


You might wonder how much you really need to know to use OS-9. 
The answer varies with your needs, and with the application 
programs you intend to use. 


However, regardless of how you intend to use your computer, there 
are some OS-9 procedures you must know. For instance, you must 
know how to load OS-9, how to prepare diskettes to store data, 
and how to make copies of data or entire diskettes. This part of 
your handbook makes these jobs easy. 


Regardless of how careful you are, there are times when things go 
wrong. When this happens, OS-9 displays an error message on the 
screen. This part of the manual also helps you to understand 
error messages and what to do about them. 
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How to Start and Exit Your 
System 


Starting your computer and initializing an operating system is 
called booting. In a sense, the computer is pulling itself up by its 
bootstraps. 


To run OS-9, Level II, you must have a Color Computer 3 with at 
least one floppy disk drive. Your OS-9 system diskette includes 
modules to support the following Color Computer hardware: 


@ Up to 512K RAM 

@ A Keyboard 

An Alphanumeric Video Display 

A Color Graphics Display 

Floppy Disk Drives (one or two) 
Joysticks (one or two) 

A Serial Printer 

An RS-232C Communications Port 


If you connect a Multi-Pak Interface to your computer, and use 
the CONFIG utility from your BASICO9/CONFIG diskette (see 
Chapter 7), OS-9 can support the following devices: 


@ As many as two external RS-232 communications cards 
@ As many as two modem paks 
@ As many as two additional floppy disk drives 

Note: The Multi-Pak Interface has four cartridge slots. 


A floppy disk controller must be in Slot 4. You can put 
modem paks, or RS-232 paks in Slots 1, 2, or 3. 
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Booting OS-9 


Use the instructions in the Color Computer Disk System manual 
to turn on your computer system. After you do, the video screen 
displays a copyright message followed by the letters, 0k. This is 
Disk Extended Color BASIC’s way of telling you that it is ready 
to get to work. It is waiting for your commands. 


To load OS-9, follow these steps: 
1. Insert the OS-9 System Master diskette into Drive 0. 
2. At the 0K prompt, type: 


DOS 


OS-9 starts. If the DOS command returns a syntax error (SN? 
ERROR), be sure you entered the command correctly. If DOS 
still returns the error, check to make sure you have installed 
your disk cartridge properly. 


3. After OS-9 displays its startup message, this prompt appears: 


yy/mm/dd hAimm:s5 
Time? 


4. Type the year, month, date, hours, minutes, and seconds in 
the format requested; then press [ENTER]. For instance, if the 
date and time is September 3, 1986, 1:22 p.m., type: 


86/09/03 13:22 (ENTER) 


Note that the time is entered in 24-hour notation and that the 
seconds (:SS) are optional. 


You can bypass this time and date prompt by only pressing 
(ENTER ]. However, if you do, OS-9 cannot provide the correct 
date when you create and save data on disk. Also, it cannot 
provide the correct date and time for application programs 
that require them. 


After you enter the date and time, the OS-9 prompt appears 
and OS-9 is now in control and ready to accept a command. 


You should always keep the OS-9 System diskette in Drive 0 
(/DO) while running OS-9 unless you have a hard disk con- 
taining your system files. An OS-9 System diskette is a 
backup copy of the OS-9 System Master diskette. The instruc- 
tions for making copies are in the next chapter. 
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Rebooting OS-9 


If you need to reboot OS-9 after the initial startup, press your 
computer’s reset button (located at the right rear of the com- 
puter). Pressing the reset button one time causes the OS-9 boot 
message to reappear. The system then loads as it did originally. 
Be sure the System Master diskette is in Drive /DO when you 
reboot. 


Pressing the reset button twice returns the computer to Disk 
BASIC. 


Exiting OS-9 


In the same manner that you use OS-9 to start operations, you 
should use OS-9 to exit or close operations. For instance, if you are 
in the middle of a process, it is unwise to suddenly turn off your 
computer. Doing so can destroy files or garble disks. 


You can usually terminate an operation by pressing or 
(E). In some instances, you must let an operation complete 
its function before you can regain control of OS-9. If you are using 
an application program, that program’s manual tells you how to 
exit the program to the OS-9 command level. 


You should always be at the OS-9 command level to turn off your 
computer. Then follow these steps: 


1. Be sure the OS-9 system prompt and cursor are displayed. 


Note: You can turn off the OS-9 cursor. If you or an 
application program has done so, the cursor does not dis- 
play at the command level. 


we) 


. Take out any floppy diskettes from the disk drives, put them 
back in their protective envelopes, and store them in a safe 
place. 


st) 


. Turn off all the equipment attached to your computer such as 
a printer or disk drive(s); then turn off your TV or monitor. 
Last of all, turn off your computer and Multi-Pak Interface (if 
you have one). If you plug your equipment into a power strip, 
you can use the power strip switch to turn off all equipment at 
one time. 
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Upper- and Lowercase Characters 


OS-9 can display both upper- and lowercase letters. However, you 
can tell it you want to use only uppercase. To do this, type: 


tmode upc [ENTER 


If you do this, you cannot type lowercase letters, and the system 
displays all uppercase letters. To switch back to both uppercase 
and lowercase, type: 


tmode -upc [ENTER 


Even when you are in the upper-/lowercase mode, you can switch 
to typing all uppercase by pressing (0}. Everything you type 
is now uppercase, but the computer can display both upper- and 
lowercase. Press (0) to switch back to upper-/lowercase. 


If you want to type only one uppercase letter, hold down 
while you press that letter. 


It does not matter to OS-9 whether you type in uppercase or low- 
ercase letters, or any combination of upper- and lowercase let- 
ters. For instance, instead of typing TMODE UPC, you can type 
tmode upc or Tmode UPC. 


OS-9 Error Messages 


Everyone makes a mistake now and then when typing com- 
mands. If you type something the operating system doesn’t rec- 
ognize, or if you ask it to do something it cannot do, it displays an 
error message. This message is a number that refers to the type 
of problem that OS-9 has encountered. For instance, if you type 
XxXXX (which is nonsense to OS-9), the system displays: 


ERROR #216 


If you don’t know the meaning of the system error number you 
have two options: (1) you can look up the reference in OS-9 
Commands under Appendix A, “Error Codes” or, (2) you can 


type: 
ERROR 216 


Kither method shows you that Error #216 means “Path Name 
Not Found.” OS-9 thought you wanted it to execute a command 
but it could not find one named xxxx. 
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Other OS-9 error messages tell you if you have used all of a disk’s 
storage space, if the computer’s memory is full, if you try to cre- 
Mm ate two files with the same name, and so on. 
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What You Need to Know 
To Use Floppy Drives 


Floppy diskettes require careful handling. You might already be 
familiar with how to take care of diskettes from reading your 
Color Computer Disk System manual. If not, or as a reminder, 
review the following points: 


Always make copies of important diskettes. The price of a 
diskette is small compared to the time it can take to 
replace destroyed data. 


Copy data you are working with regularly. If you experi- 
ence a power failure while using your computer, the data 
on any diskettes you have in a drive can be destroyed. 
Other accidents can happen as well. 


Always keep the protective paper or cardboard envelope on 
your diskette when it is not in use. 


Your drive accesses a diskette through the oblong slot in 
the diskette’s jacket. Never touch the diskette through 
this hole. The oil from even the cleanest hand can destroy 
data, making the diskette useless. 


Do not bend diskettes. 


Store diskettes away from excessive heat, dust, and any 
magnetic source. Even components in disk drives, video 
displays, TVs, and electric motors can garble the data on 
diskettes. 


If you must write on a diskette label after placing it on 
the diskette, use only a soft felt pen. 


Do not switch your computer, disk drive(s), or Multi-Pak 
interface on or off while you have a diskette in a disk 
drive. 


Getting Started With OS-9 


Write Protection for Diskettes 


Lo Write-Protect Notch 


= Tad 


Most diskettes have a square notch cut from one corner. This is a 
write protect notch. If you place a special adhesive tab (supplied 
with diskettes) over both sides of this notch, your computer can no 
longer write (store) data on it. This feature protects diskettes from 
inadvertent destruction of data. 


Removing the tab again lets you write data onto the diskette. 


Disk Drive Names 


OS-9 has its own method of referring to your disk drives. What 
your Color Computer Disk System manual calls Drive 0, OS-9 calls 
Drive /DO. This is your first drive if you have more than one 
floppy disk drive connected to your system. Subsequent drives are 
named /D1, /D2, and so on. 


If you have a hard disk attached to your system, OS-9 refers to it 
as Drive /HO. A second hard disk drive is named /H1. 
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Making Copies of Diskettes 


Before you can store information on a diskette, you must format it. 
Formatting is the process of magnetically arranging a disk’s sur- 
face so that OS-9 can store and locate information. The following 
steps tell you how to format a diskette. Format at least two 
diskettes at this time to use in making backups (copies) of your 
two OS-9 system diskettes. If you have other important diskettes 
to backup, format as many diskettes as you require. 


Formatting With One Disk Drive 


1. If you have not already done so, place a write-protect tab on 
your System Master diskette. Then, turn on and boot your 
computer as described in Chapter 2. 


2. With the OS-9 System Master diskette in your drive, type: 
load format (ENTER). 


3. Select a diskette that does not contain data or that contains 
data you do not want to keep. Make sure it does not have a foil 
tab covering the write-protect notch. Put it in your disk drive 
(Drive /DO) in place of your OS-9 System Master diskette and 


type: 
format /d@ 
The following prompt appears: 


COLOR COMPUTER FORMATTER 
Formatting drive /d@ 

y yes) or n Cnod 

Ready? 


4. Press to begin formatting. OS-9 asks you for a Disk Name:. 
Type any name, using a maximum of 32 characters. For 
example, you can type s to name the diskette “s.” 


Next OS-9 verifies that the diskette is formatted properly. The 
screen shows each track number in hexadecimal notation dur- 
ing verification. A track is a concentric ring around the 
diskette on which information is stored. 
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. When formatting is complete, OS-9 shows you the Number of 


good sectors. This number depends on the type of disk drive 
you are using. For a 35 track, single-sided drive, the number 
should be $000276 (hexadecimal 276 sectors). The OS-9 prompt 
and cursor reappear. Remove the newly formatted diskette from 
the drive, and store it in a safe place until you are ready to use 
it, 


Format as many diskettes as you need by following Steps 3 
through 5. 


Formatting With Two Disk Drives 


1. 


If your computer is off, turn it on, and boot OS-9 as outlined in 
Chapter 2. 


. At the system prompt (0S9:), type format /d1 (ENTER}. The 


screen shows: 


COLOR COMPUTER FORMATTER 
Formatting drive /d1 

y Cyes) or n Cno)d 

Ready? 


. Insert a blank disk, or one which does not contain data you 


want to keep, into Drive /D1, and close the latch. Be sure the 
diskette does not have a foil tab covering the write-protect 
notch. Press (Y}. 


. OS-9 formats the diskette; then asks you for a Disk Name:. 


Type any name, using a maximum of 32 characters. For 
example, you can type s to name the diskette “s.” 


Next OS-9 verifies that the diskette is formatted properly. The 
screen shows each track number in hexadecimal notation dur- 
ing verification. A track is a concentric ring around the 
diskette on which information is stored. 


. When formatting finishes, OS-9 shows you the Number of 


good sectors. This number depends on the type of disk drive 
you are using. For a 35-track, single-sided drive, the number 
should be $000276 (hexadecimal 276 sectors). The OS-9 prompt 
and cursor reappear. Remove the newly formatted diskette from 
the drive, and store it in a safe place until you are ready to use 
it. 
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Format as many diskettes as you need by following the same 
procedure. 


Using the Backup Command 


BACKUP is one OS-9 command that you can expect to use fre- 
quently. It is the command you use to make copies of your 
diskettes. We strongly recommend that you now use the fol- 
lowing instructions to make copies of your OS-9 system 
diskettes. You can only copy diskettes that are created in the 
same type of disk drive you are using. Your OS-9 system diskettes 
are 35 track, single sided. 


BACKUP uses two terms you need to understand. They are source 
and destination. A source diskette is the diskette that contains the 
program, file or data that you want to backup. The destination 
diskette is the blank formatted diskette you prepared to receive 
the copied data. 


Note: Some application programs you buy do not let you 
make copies of their diskettes. Check the program manual 
for information on protecting the data on these diskettes. 


Making Copies With One Disk Drive 


1. If your computer is off, turn it on, and boot OS-9 as outlined 
at the beginning of Chapter 2. 


2. At the system prompt (0S9:), type: 


backup /d@ #32K 


This tells OS-9 to make a backup of the diskette in Drive /DO. 
The screen displays the following prompt: 


Ready to backup from /d@ to /d@ 
ce. 


3. Leave the System Master diskette in Drive /DO to make a 
backup of it. To back up one of your other diskettes, for exam- 
ple the BASICO9/CONFIG diskette, remove the System Master 
diskette and replace it with the diskette you want to copy. 


4. Press (Y} when you are ready to continue. The screen displays: 


Ready Destination, hit a key: 
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5. Replace the source diskette with the destination diskette. Then, 
press the space bar to continue BACKUP. 


When you back up one diskette to another, any data previ- we 
ously existing on the destination diskette is overwritten 
(destroyed). OS-9 gives you a chance to make sure you have 
inserted the proper destination diskette by displaying the 
message: 


DISK NAME 
is being scratched 
ie Ps 


“Scratched” means that OS-9 is going to replace any data on 
the diskette with new data from the source diskette. BACKUP 
also gives the destination diskette the same name as the source 
diskette—the destination becomes a duplicate of the source. 


6. Press (Y) to keep going. The screen asks you to: 
Ready Source, hit a key: 


7. Remove the formatted diskette from Drive /DO, and replace it 
with the source diskette that contains the data you want to \y 
copy. Press the space bar. 


In a moment, a prompt asks you to: 
Ready Destination, hit. a key: 


8. Remove the source diskette and replace it with the destination 
diskette. Press the space bar. 


9. Continue switching diskettes as the screen instructs you until 
you see: 


Sectors copied: $8276 
Verify pass 


Followed in a moment by: 


Sectors verified: $9276 
OS9: 
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The diskette now in your drive, the destination diskette, is a 
duplicate of the source diskette. If you copied the System Master 
or the BASICO9/CONFIG diskette, store it in a safe place, and 
use the copy as your working diskette. Reserve the original 
diskette for making future backups. 


Note: For computers with 512K of memory, OS-9 can 
backup a diskette faster if you replace #32K in Step 2 with 
#56K. 


Making Copies With Two Disk Drives 


1 


If your computer is off, turn it on, and boot OS-9 as outlined 
at the beginning of Chapter 2. 


. At the system prompt (0S9:), type: 


backup /d@ /d1 #32K 
This tells OS-9 to make a backup of the diskette in Drive /DO. 
The screen displays the following prompt: 


Ready to Backup from./d0 to /d1 
foe 


. Leave the System Master diskette in Drive /DO to make a 


backup of it. To back up one of your other diskettes, for exam- 
ple the BASICO9/CONFIG diskette, remove the System Master 
diskette and replace it with the diskette you want to copy. 


. Press (Y] when you are ready to continue. 


When you back up one diskette to another, the process over- 
writes or destroys any data previously existing on the destina- 
tion diskette. OS-9 gives you a chance to make sure you have 
inserted the proper destination diskette by displaying the 
message: 


DISK NAME 
is being scratched 
Ok ? 


“Scratched” means that OS-9 replaces any data on the des- 
tination diskette with new data from the source diskette. 
As well, BACKUP gives the destination diskette the same 
name as the source diskette—the destination becomes an 
exact duplicate of the source. 
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6. Press (Y} to keep going. 
Copying continues. When the procedure ends, you see: 


Sectors copied: $9276 
Verity pass 


Followed in a moment by: 


Sectors verified: $8276 
OSS: 


The diskette in Drive /D1 is now a duplicate of the source 
diskette. If you copied the System Master or the BASIC09/ 
CONFIG diskette, store it in a safe place, and use the copy as 
your working diskette. Reserve the original diskette for making 
future backups. 


Note: For computers with 512K of memory, OS-9 can backup 
a diskette faster if you replace #32K in Step 2 with #56K. 
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Organization, Commands, 
and Keys 


Chapter 4 


Files and Directories 


Before you can use OS-9 extensively, you need to know how the 
system organizes and stores data on disk. The information in this 
section is true for both floppy diskettes and hard disks. However, 
because of the greater storage capacity of a hard disk, it is of 
particular importance to hard disk users. 


About Files 


Consider the information stored on disks to be of two basic types, 
programs and data. A program is code that causes your com- 
puter to execute a task. Data is information that a program uses 
or that a program creates. 


All the information that OS-9 stores on disks, whether program or 
data, is stored in units called files. Whenever a program creates 
a file, OS-9 defines a portion of your disk to store it. It keeps the 
location of the file in a special list (called a directory), also located 
on the disk, so that it knows where to find your program or data 
the next time you want it. 


About Directories 


A directory is a storage space for filenames, other directory 
names, or both. 


After you format a disk, it contains one directory called the 
ROOT directory. However, a disk can have many directories. For 
instance, besides the ROOT directory, your System Master 
diskette contains the CMDS and SYS directories. The ROOT and 
CMDS directories are especially important to you. 


When you boot OS-9, you automatically begin operation from 
these two directories. The ROOT directory becomes your current 
data directory and the CMDS directory becomes your current 
execution directory. 


Whenever you ask OS-9 to store a file on a diskette, it automati- 
cally stores it in the current data directory (the ROOT direc- 
tory), unless you tell it otherwise. If you ask OS-9 to execute a 
command or program, it automatically looks for that command or 
program in the execution directory (the CMDS directory), unless 
you tell it otherwise. 
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Every OS-9 directory can also contain other directories, called 
subdirectories. For instance, SYS, and CMDS are established as | 
subdirectories of the ROOT directory. Put in chart form, your 


ROOT directory with its subdirectories looks like this: ww | 
a ROOT DIRECTORY — 
CMDS SYS 
Figure 4.1 


But there are also files in the ROOT directory, OS9Boot and 
Startup are two. The full ROOT directory might look like this: 


ROOT So 
wh 
Startup 
WwW 


CMDS 


Figure 4.2 


You can create another subdirectory of the ROOT directory if you 
want. For instance, if you created a directory named FAMILY, the 
chart of the ROOT directory looks like this: 


ROOT DIRECTORY 
OS9Boot 
Startup 


CMDS FAMILY 


Figure 4.3 
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After you create the FAMILY directory, you can also create other 
directories in it. Suppose you create two subdirectories named 
PLEASURE and WORK. The chart organization is as follows: 


ROOT DIRECTORY 
OS9Boot 
Startup 
CMDS i FAMILY a SYS 
PLEASURE WORK 


Figure 4.4 


The directories you create also can hold files. If you created three 
files each in the PLEASURE and WORK directories, the chart 
might look like this: 


ROOT DIRECTORY 
OS9Boot 
Startup 
CMDS [ FAMILY 7 SYS 
PLEASURE WORK 
mom mom 
dad dad 
joe joe 
Figure 4.5 


You can continue to create files and subdirectories in any or all of 
your disk’s directories until you fill the disk’s storage space. 
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Multiple Directories 


There is nothing wrong with storing all your files in the ROOT 
directory. Doing so makes it easy to access them because they are 
always in your data directory. 


However, creating multiple directories makes it easy to keep your 
data organized when you have many files, or if more than one 
person is using the same disk. Such a multiple-directory organi- 
zation is especially helpful when using hard disks, which can 
store hundreds of individual files. 


Also, when you have multiple directories, you can store files hav- 
ing the same name in different directories without conflict, such 
as in the PLEASURE and the WORK directories of Figure 4.5. 


About File and Directory Names 


The file and directory names shown so far consist only of letters 
of the alphabet, but you can use other characters and symbols in 
a file or directory name as long as each name begins with a let- 
ter. The following is a complete list of acceptable characters: 


@ Uppercase letters: (A-Z) 

@ Lowercase letters: (a-z) 

@ Decimal digits: (0-9) 

@ The underscore character (__) and the period (.) 


You can include as many as 29 characters in a file or directory 
name. 


Examples of Filenames 


The following are samples of filenames that OS-9 can recognize: 


mydata samfile 

mydatal Dollar_gifts 
records.srt help.file 

XXX.xx file#1.txt 
progl1.bas program.sourcecode 
prog2.bas program.opcode 
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Examples of invalid filenames are: 


His*hers: ..cscsscee4 because * is not a valid character for 
names 
ATA 5 Seo oaeRos because the name does not begin with 
a letter 
COST INT 2. 4.0¢44 because + is not a valid character for 
names 
100_dollar_gifts ...because names cannot begin with a 
digit 
About Pathlists 


Because you can organize OS-9 disks into multiple levels, you 
need a way to tell the system where to find directories and files. 
The directions you give are called pathlists. 


A pathlist is exactly what its name implies—a path (or route) to 
the device, directory, or file you want to access. For instance, if 
you are in the ROOT directory (see Figure 4.5) and want to look 
at the contents of a file in the WORK directory, you must tell 
OS-9 how to get there. The pathlist from the ROOT directory to 
the Dad file is family/work/dad. OS-9 expects you to separate 
the junctions of pathlists with slashes. To look at the contents of 
Dad, you type: 


list family/work/dad 


Because you are accessing a file on the current disk, you do not 
need to specify a drive name. Because every disk contains a 
ROOT directory, and all other directories and files branch from it, 
ROOT is always implied in a pathlist. If Figure 4.5 represented 
the diskette in Drive /D1, the pathname to the Dad file would be 
/di/family/work/dad. 


Depending on the location of the directory or file you want to 
access, a full pathlist need not contain any more than the name 
of a drive, the name of a directory, or the name of a file. For 
instance, the complete pathlist from the ROOT directory of Fig- 
ure 4.5 to the Startup file is startup. To look at the contents of 
Startup, type: 


list startup 
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Anonymous Directory Names 


To save time, or if you do not know a full pathlist, you can refer 
to the current directory, or to a higher-level directory, using an 
anonymous name, or name substitute, as follows: 


@ One period (.) refers to the current directory 


@ Two periods (..) refer to the parent of the current direc- 
tory (the next highest-level directory). 


@ Three periods (...) refer to the directory two levels up, and 
so on. 


You can use an anonymous directory name in place of a pathlist 
or as the first name in a pathlist. Some examples are: 


Jit os lists names in the current data direc- 
tory’s parent directory. 


del ../temp (ENTER| deletes the file called Temp from the 
current data directory’s parent 
directory. 


Anonymous names can refer to either execution or data directo- 
ries, depending on the context in which you use them. 


About Device Names 


In the same manner that OS-9 has names for its commands, it 
also has names for its devices. These names are abbreviations of 
actual device names. For instance, instead of typing Disk Drive 0 
to refer to your first disk drive, you only need to type /D@. To 
refer to your printer, type /P. OS-9 windows are named /W 
through /W7. 


All of OS-9’s device names are preceded by a slash—this is how 
OS-9 can tell you are referring to a device rather than a direc- 
tory or file. When you purchase your System Master diskette, OS- 
9 is configured to recognize two disk drives, a printer, and one 
terminal port. For information on how to configure your system to 
recognize other devices, see Chapter 7. 
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Commands and Keys 


You already put OS-9 to work with commands such as FORMAT 
and BACKUP. In these cases the manual told you exactly what to 
do to accomplish a very specific task. If you want to strike out on 
your own, you should know some additional background 
information. 


Typing Commands 


As explained earlier, some OS-9 files are programs. You tell OS-9 
to execute these programs by typing the program (file) name and 
pressing [ENTER]. You are then issuing a command to OS-9. That’s 
all a command is, the name of a program for the system to exe- 
cute. The following are some rules about commands: 


@ You can enter a command whenever the screen displays 
the system prompt (0S9:). 


@e A command consists of one word, the command name. A 
command line consists of one or more command names 
and their associated parameters and modifiers. Parame- 
ters and modifiers are special information you include 
with a command that provide necessary data for the com- 
mand to operate, or that affect the command’s operation. 


@ A command line can have a maximum of 198 characters 
including any combination of upper- or lowercase letters. 
To execute a command, press [ENTER]. For example, to clear 
the screen, type: 


display @c 


Editing Commands 


OS-9 is very particular about the commands you type. If you 
make any mistake, OS-9 either does not understand (and tells you 
so with an error message) or does the wrong thing. 


If you see that you made a mistake before you press [ENTER], you 
have two choices: (1) use or to move the cursor to the 
mistake, and retype that portion of the line, or (2) press 
or to erase the line you are typing, and start over. 
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Command Parameters 


You can follow a command name with one or more parameters 
that give OS-9 more specific instructions. For example, in the 
command line: 


list filet 


LIST is the name of the command that displays the contents of a 
text file. Filel, the specified parameter, is the name of the file 
that you want displayed. 


Note: In a command line, always use spaces to separate 
parameters from their command, and from each other. 
Parameters cannot contain spaces. Chapter 6 discusses 
parameters for each OS-9 command. 


Some commands have more than one parameter. For instance, 
COPY requires two parameters: the name of the file being cop- 
ied, and the name of the new file you want COPY to create. If you 
want to copy a file called Startup, and call the copy Newstartup, 
your command line reads: 
COPY, the command 
name. 


The name of the file 
to copy 


The name of the copy 


cause the command 
line to execute. 


7 You press [ENTER } to 


copy startup newstartup 


Using Options 


Command lines can also contain another type of parameter, called 
an option. An option changes the way a command performs. For 
instance, the command DIR, without parameters, shows the name 
of all files in the current data directory. 
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However, if you add the E option as a parameter to the com- 
mand, like this: 


dir e| ENTER 


the output includes not only the names of the files, but also com- 
plete statistics about each file—the date and time created, size, 
security codes, and so forth. 


To display complete information about each file in SYS, type: 
dir sys e 


Using Commands 


As described in Part 1, OS-9 acts in much the same manner as 
an office manager. It looks after the operation of your computer 
and equipment. Because OS-9 is only a manager, it expects you 
to make the necessary decisions. 


For example, suppose you have an important file named Hotstuff 
that you want to copy. Before giving it to your office manager 
(OS-9), you must make executive decisions, such as: 


@ Do you want the copy on disk, paper, or the computer 
screen? 


@ If you want the copy on disk, which disk? 


@ If you want the copy on the same disk, what name do you 
want to give the second copy so OS-9 is not confused? 


@ If you want the copy on the computer screen, do you want 
the display to pause when it fills the screen? 


You make the decisions, OS-9 manages the job. For instance, if 
your decision is to copy Hotstuff from one diskette to another, 
you might type the following command line: 


copy /d@/hotstuff /d1/hotcopy 
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This is how OS-9 sees your command: 


The name of the 
command 


The disk drive 


containing the file to be 
copied 
The name of the file to 
copy 
The disk drive that is to 
receive the new file 

ig The name of the copy 


copy /d@/hotstuff /di1/hotcopy 


This command line tells OS-9 to copy a file named Hotstuff from 
your floppy disk Drive /DO to a second floppy Drive /D1. The file 
copy is given the new name, Hotcopy. 


You only need to know the name of the file you want to copy, on 
which disk it is located, and the disk on which you want the new 
copy. OS-9 manages the operation for you. 


Accessing Commands 


OS-9 has two ways to access commands. Some commands reside 
on a disk. When you type the command name and press (ENTER}, 
OS-9 must look on the disk, load the program into the comput- 
er’s memory, and then execute it. 


Other commands are loaded into your computer’s memory at 
startup, or you can load them into memory later. When you call 
a command that is in memory, it is executed immediately. There 
is no delay while OS-9 finds it on disk. 
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Commands from Disk 


When you give OS-9 a command that it cannot find in memory, it 
looks for the command in the current execution directory. If it 
cannot find it there, it checks the current data directory. If it still 
cannot find it, the system issues Error Message #216, Path Name 
Not Found. If the command you want executed is in a directory 
other than the current directory, you must tell OS-9 where to find 
it. Remember, when initialized, OS-9 sets the CMDS directory of 
the system disk to be the execution directory. 


For instance, suppose you booted your system using a diskette 
configured like the example we used in Chapter 4: 


ROOT DIRECTORY 


OS9Boot 
Startup 


CMDS FAMILY 


i 7 SYS 


PLEASURE WORK 


’ V 


mom mom 
dad dad 
joe joe 
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When the system starts, the ROOT directory is the data direc- 
tory, and the CMDS directory is the execution directory. Now, 
suppose you had a program named Expenses in the family 
directory: 


ROOT DIRECTORY 


OS9Boot 
Startup 


CMDS FAMILY 


SYS 
a 
expenses 


PLEASURE WORK 


mom mom 
dad dad 
joe joe 


(Remember that a program and a command are really the same 
thing.) 


You can now access (use) the expenses program in two ways. One 
way is to specify a pathlist from the ROOT directory to execute 
Expenses, such as: 


/d@/family/expenses 


Another way is to change the execution directory. 


Changing the Execution Directory 
To change the execution directory to the FAMILY directory, type: 
chx /d@/family 


Or specify a pathlist relative to the current execution directory, 
such as: 


ene -; -/family 


To execute the Expenses program, you now only need to type 


expenses ENTER }. 
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However, after you change the execution directory, to use a com- 
mand in the COMMANDS directory, you must tell OS-9 where to 
find it. For example, to format a new diskette in Drive /D1, type: 


/d@/cmds/format /d1 


Changing the Data Directory 


Suppose that the Expenses program keeps track of work and 
pleasure expenses for Mom, Dad, and Joe. Unless you tell OS-9 
otherwise, it looks for data files in the current data directory, the 
ROOT directory. To tell OS-9 to look for data files in the PLEA- 
SURE directory, type: 


chd family/pleasure 


The slash between FAMILY and PLEASURE tells the system that 
PLEASURE is a branch of FAMILY. Subordinate directories and 
files are always separated from their parent in this way. 


Now, when Expenses needs data, it knows to look in the PLEA- 
SURE directory. 


Changing System Diskettes 


Although it is preferable to leave the system diskette in place 
while the system is running, particularly with multiuser sys- 
tems, there might be times when you need to use another 
diskette. Only remove the current diskette when the screen dis- 
plays the OS-9 prompt, followed by the cursor. If you do remove 
the system diskette and begin to use another one, use the CHD 
and CHX commands to tell OS-9 where you want to be located on 
the new diskette. (For directions, see Chapters 2 and 6.) Those 
commands set both directory pointers, data and execution, for the 
new diskette. 


While using a program or command, do not remove a diskette and 
insert another unless the program or command asks you to. You 
can lose data, or entire files, if you do. 
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Video Display and Keyboard Functions 


OS-9 has many features that expand the capability of the Color 
Computer’s video display and keyboard. 


e The video display has upper-/lowercase, screen pause, 


graphics functions, and 80 column displays if you have a 
monitor connected. 


The key provides an alternate key function. Holding 
down while pressing another key sets the high order 
bit of the character pressed. That is, it adds 128 to the 
normal ASCII value produced by that key. Holding down 
while pressing any other key produces a graphics 
character on the standard VDG screen. If you are using 
windows, lets you produce international characters. 
(See OS-9 Windowing System Owner’s Manual for more 
information). 


The keyboard has an auto-repeat function. Holding down 
a key causes the character to repeat until you release the 
key. This function operates properly only when the disk 
drives are not in use by a program. 


You can deal with the video display and keyboard together 
as though they are a file. You can receive input from the 
keyboard and send output to the video screen using the 
device name /TERM. 


Special Keys 


The following keys and key sequences have special significance 


to OS-9. 

ALT Produces graphic characters on a stan- 
dard VDG screen or international 
characters with windows. Press 
char (where char is a keyboard charac- 
ter). 

A control key. 

or Stops the current program execution. 

(CTRL J(E) 

or Moves the cursor to the left one space. 


ed 


(eTRL }(—] 
(cal }(] 
(oTrL }(-) 


or 


(CLEAR }* 
[SHIFT J( CLEAR }* 


(SHIT) Jor 
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Generates an underscore character. 
Generates a left brace ({). 
Generates a right brace (}). 
Generates a tilde (~). 

Generates a backslash ( \ ). 


Performs an ESCAPE function, and 
sends an end-of-file message to a pro- 
gram receiving keyboard input. To be 


recognized, must be the 
first thing typed on a line. 


Performs a CONTROL C function by 
interrupting the video display of a pro- 
gram. The program runs as a back- 
ground task. 


Selects the next video window. 
Selects the previous video window. 


* You must have established windows 
for this function key to have any 
effect. See ‘““Using Windows” in 
Chapter 7. 


Toggles the keyboard mouse on and off. 
The keyboard mouse uses the arrow 
keys and the two function keys (F1 
and F2) to simulate an external 
mouse. When keyboard mouse is on, 
the normal functions for the arrow and 
function keys is suspended. 


Deletes the current line. 


Activates or deactivates the shift lock 
function. 


Generates a vertical bar ((). 
Generates an up arrow (’). 


Generates a left bracket ([). 
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(oTAL (9 } 


(CTRL) 


Generates a right bracket ( ] ). 


Redisplays the last line you typed and 
positions the cursor at the end of the 
line, but does not process the line. 
Press to process the line, or edit 
the line by backspacing. If you edit, 
press again to display the 
edited line. 


Redisplays the current command line. 


Temporarily halts video output. Press 
any key to resume output. 


Performs a carriage return or executes 
the current command line. 
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OS-9 Toolkit 


You now know about a number of OS-9 commands that can help 
you set up and use your computer system. There are many more 
commands available. This chapter contains information about a 
few of the most helpful commands. Becoming acquainted with 
these makes it easy for you to use other commands and func- 
tions. OS-9 Commands contains more information and a com- 
plete reference to all OS-9 commands (including those you have 
already discussed). 


Viewing Directories 


To look at your disk directories use the DIR command. For exam- 
ple, to view the contents of the current data directory, type: 


dir (ENTER 


If your data directory contains more filenames than can display 
on the screen at one time, the display pauses. Press the space bar 
to cause additional files to scroll onto the screen. 


You can also view your execution directory in a similar manner. 
This time you must include the command option, x. Type: 


dir x |ENTER 


If you want to look at a directory on a disk drive other than the 
current drive, specify a complete path for OS-9 to follow, includ- 
ing the disk drive name. For example: 


dir /d®/FAMILY/WORK 


Creating Directories 


Before you can store data in a directory other than the ROOT 
directory, you must create that directory with MAKDIR. For 
instance, to create a FAMILY directory on your Drive /DO 
diskette, type: 


makdir /d@/FAMILY [ENTER] 
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Deleting Directories 


You can also delete directories you create. When you delete a 
directory you also delete any files or subdirectories it con- 
tains; so use this command with caution. To delete a direc- 
tory, follow these steps. 


1. Use DIR to view the contents of the target directory and any of 
its subdirectories. 


2. Copy any files you want to keep into a directory outside of the 
directory you want to delete. 


3. Type: 
deldir dirname 


where dirname is the name of the directory you want to delete. 
The screen shows: 


Deleting cirectory Tile: 
List directory, delete directory; or quit 7 
Ci/aya? 


4. You now have three options: 


a. To again confirm the contents of the directory before you 


delete it, press {1} (ENTER). 
b. To initiate the deletion process, press (d} [ENTER]. 


c. To quit the process and leave the directory intact, press (q] 


[ENTER J. 


If you try to delete directories other than the ones you create, 
OS-9 might display Error #214, No Permission (you do not own 
the directory or have write permission for it). For information on 
handling such directories, see the ATTR command in OS-9 
Commands. 


Displaying Current Directories 


There are times when you need to know the names of your cur- 
rent data and execution directories. The PWD and PXD com- 
mands make this possible. To determine your current data 
directory, type: 


pwd (ENTER 
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The command displays the path from the ROOT directory to the 
current data directory. For instance, if your current data direc- 
tory is PLEASURE (see Figure 4.5 in Chapter 4) the display is: 


/DO/FAMILY/PLEASURE 
To discover your current execution directory, type: 


pxd 
The screen might display: 
/D@/CMDS 


A standard convention of OS-9 is to capitalize directory names. If 
you follow this convention when creating directories, you can 
always tell which files are directories at a glance. 


Copying Files 


COPY, like BACKUP, provides file security. If something hap- 
pens to one file, you can use a copy. Also, you might want to copy 
a command or program to use in more than one directory, or you 
might want to use the same data on more than one computer. 


Suppose you are in the PLEASURE directory of a diskette confi- 
gured as in Figure 4.5. Your execution directory is the FAMILY 
directory, where you are using the Expenses program. Because 
the FAMILY directory does not contain any OS-9 commands, you 
have to change the execution directories whenever you want to use 
them. 


You can make your work easier by copying the Expenses pro- 
gram to the CMDS directory. To do this, first make the CMDS 
directory your data directory by typing: 


chd /d@/CMDS (ENTER] 
Then copy the Expenses file to the CMDS directory by typing: 
copy /d®/FAMILY/expenses expenses [ENTER] 


Now, Expenses is in the CMDS directory, and you do not need to 
change the execution directory to FAMILY to use it. 
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Likewise, if the ROOT directory is your data directory, and you 
want to copy the Mom file from the WORK directory to the ROOT 
directory, type: 


copy family/work/mom mom 


You can copy any file between directories and between disks. To 
do so, you must provide the COPY command with a pathlist for 
the location of the original file and for the destination of its copy. 


Deleting Files 


You can delete files in any directory using the DEL command, 
such as: 


del myfile 


You can delete a file in the current execution directory by using 
the —x parameter. For instance, to delete Myprogram from the 
current execution directory, type: 


del -x myprogram 


If the file you want to delete is in a directory other than the cur- 
rent data directory or the current execution directory, you must 
specify the full pathlist to the file. For instance, suppose you are 
in the ROOT directory of a diskette configured as Figure 4.5. To 
delete the Joe file in the WORK directory, type: 


del family/work/joe 


If the file you want to delete is on a drive other than your cur- 
rent drive, include the drive name in your pathlist, such as: 


del /d1/family/work/joe 


If you attempt to delete a file you did not create, OS-9 might dis- 
play Error #214, No Permission. For information on deleting such 
files see the ATTR command in OS-9 Commands. 


Renaming Files 


OS-9 lets you change the names of files. Suppose Joe leaves home, 
and you now want to keep track of expenses for Sue. To change 
the name of the Joe file to Sue, type: 


rename family/pleasure/ joe sue | ENTER 


6-4 


OS-9 Toolkit / 6 


Looking Inside Files 


LIST is a command that lets you examine files that consist of text 
characters. For instance, to view the Dad file from the WORK 
directory, you might type: 


list family/work/dad 
The contents of the file appears on the screen. 


If you use LIST to display a file that is not a text file, it pro- 
duces a meaningless display. 


Loading Command Modules into Memory 


When using OS-9, you might notice that some commands begin 
execution immediately, while others require access to the disk 
drive before they execute. The OS-9 commands you need most 
often load into memory at startup, so they are available for 
immediate use. If you plan to frequently use a command that is 
not in memory, you can load it. 


For instance, the DSAVE command lets you copy an entire direc- 
tory from one disk to another. To place the DSAVE module into 
your computer’s memory, first be sure your execution directory is 
the CMDS directory, then type: 


load dsave | ENTER 


Now you can use DSAVE as many times as you want, without 
waiting for OS-9 to find it on disk. 


Listing the Command Modules in Memory 


At startup, OS-9 loads into memory the commands you use most 
often. If you are not sure whether a command already resides in 
memory, you can check using the MDIR command. To display a 
directory of the modules in your computer’s memory, type: 


mdir (ENTER 


A list of all the modules in your computer’s memory appear on 
the screen. The names you see are of modules OS-9 uses to boot 
and handle system operations and the commands it loads into 
memory when you boot the system. 
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Deleting Modules from Memory 


After you load a module into memory, you can also delete it. The 
process is called unlinking. To delete the DSAVE command from 
memory, type: 


unlink DSAVE 


Some modules might require unlinking more than once, depend- 
ing on the number of times they were linked. 


Do not attempt to unlink modules that you did not install in 
memory with the LOAD command. 


Using Other Commands 


OS-9 has nearly 50 commands and functions. This chapter has 
mentioned only a few. Not only are there other commands avail- 
able through OS-9, several of the commands presented here have 
additional options. 


The guidelines you learned in this handbook provide the back- 
ground you need to make use of OS-9’s many other capabilities. 


By referring to OS-9 Commands you can learn how to create 
files, create procedure files to accomplish complicated tasks, send 
information to your printer, transfer data between devices, exe- 
cute more than one task at the same time, and much more. 
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Customizing Your System 


‘f™~ Your OS-9 operating system is originally configured in a certain 
' way. For instance, it is set up to recognize two floppy disk drives, 
but no hard drives. It is set up to recognize a printer or one extra 
terminal. It does not recognize a modem. It assumes that you only 
want 32 characters across your computer’s display screen. It pro- 

vides all of the OS-9 commands. 


Using the CONFIG utility from the BASIC09/CONFIG diskette 
that came with your OS-9 package, you can create system 
diskettes that match the computer system you have. Before pro- 
ceeding further, be sure you have a working copy of the BASIC09/ 
CONFIG diskette and a blank, formatted diskette. You can use 
the instructions in “Making Copies of Diskettes” in Chapter 3 to 
create a working copy of the BASICO9/CONFIG diskette and to 
create a blank, formatted diskette. 


Creating a New System Diskette 


om To create a new system diskette make sure you have a newly 
formatted diskette on hand, then follow these steps: 


1. Take out the System Master diskette, and replace it with the 
BASIC09/CONFIG diskette. Type: 


chx /d@/cmds | ENTER 
chd /d@ {ENTER 
config 


The first question the screen asks is: 


HOW MANY DRIVES DO YOU HAVE: 

1 ~ DNE DRIVE. TALLY 

2 - TWO OR MORE DRIVES 
SELECTION. (13,24 


2. If you’re using a single-drive system, press {1}. If you have 
more than one drive, press (2). 


If you indicated that you have two or more drives, CONFIG 


cy prompts: 


ENTER NAME OF SOURCE DISK: 
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and 
ENTER NAME OF DEST. DISK: 


Type the appropriate drive name (/D0, /D1, etc.) at each 
prompt. 


. OS-9 informs you that it is: 


BUILDING DESCRIPTOR LIST 
PLEASE WAIT 


OS-9 is putting together a list of the various devices you 
might want to use with your computer. When it finishes, it 
shows you the list: 


CONFIG 
ARROWS - UP/DOWN/MORE/BACK 
S = SEL/UNSEL H - HELP D = DONE 
LTEM Sel 
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To view the rest of this menu, press (>). Now the screen 


shows: 
cr CONFIG 
ARROWS - UP/DOWN/MORE/BACK 
S ~ SELJUNSEL = HELE D = DONE 
SEL. 
D3_355 
DDD#_35S 
DO_40D 
D1_4@D 
D2_40D 
DDD9O_44D 
D1_80D 
D2e_8aD 
4. You can choose the various devices you plan to use with your 
computer from this list. To choose a device, use [4] or to 
move to the device. The + shows the device you’ve chosen. 
Then, press (S} (for Select) to display an X in the SEL 
oo (“Selected”) column. Pressing (S$) again cancels the selection. 
You can move back and forth between the first and second 
screens by pressing either (from the first screen) or 
(from the second screen). Here’s a short description of each 
device listed on this screen. To display helpful information 
about a device, position the > on its line in the list, and press 
(H} for Help. Then, press the space bar to make the help 
information disappear. The devices on this screen are: 
r A printer that connects to the RS-232 serial port 
on your computer. 
Tl A terminal using the standard RS-232 port (in 
addition to your main computer display). 
fy A terminal using the optional RS-232 commu- 
nications pak in Slot 1 of the Multi-pak Inter- 
face. T2 supports a full baud rate range. Use T2 
aN in addition to your main computer display alone, 


or in addition to your main computer display and 
a “T1” type terminal. 
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T3 


M1 


M2 


PIPE 


DO0_35S 


D1_35S 


D2_35S 


D3_35S 


DDDO0_35S 


DO_40D 


D1_40D 


D2_40D 


DDDO_40D 


D1_80D 


D2_80D 


Another terminal using the optional RS-232 
communications pak in Slot 2 of the Multi-pak 
Interface. 


A modem using an optional 300 baud modem 
pak. 


A modem using an optional 300 baud modem 
pak. 


Lets you use the PIPE utility in OS-9 (a utility 
that takes the information a program puts out 
and uses it as input data in another command). 


Floppy Disk Drive /DO, single sided, 35 tracks. 
Floppy Disk Drive /D1, single sided, 35 tracks. 
Floppy Disk Drive /D2, single sided, 35 tracks. 
Floppy Disk Drive /D3, single sided, 35 tracks. 


Default Disk Drive /DD using Drive /DO, single 
sided, 35 tracks. Select one default drive — the 
drive where you keep your system diskette. 


Floppy Disk Drive /D0, double sided, 40 
cylinders. 


Floppy Disk Drive /D1, double sided, 40 
cylinders. 


Floppy Disk Drive /D2, double sided, 40 
cylinders. 


Default Disk Drive /DD using Drive /DO, double 
sided, 40 cylinders. Select one default drive — 
the drive where you keep your system diskette. 


Floppy Disk Drive /D1, double sided, 80 
cylinders. 


Floppy Disk Drive /D2, double sided, 80 
cylinders. 
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You must select a “DO” device as your first disk drive—use 
D1, D2, and D8 devices for additional floppy disk drives. Select 
the drive that matches the drives you have on your system. If 
you are not sure, check with your supplier. To use extra ter- 
minals and modems, you must connect them via a Multi-Pak 
Interface. 


. As you finish choosing among the devices on the first screen, 


press to display another screen of devices: 


. When you finish selecting devices, press (0D) for Done. The 


screen asks: 


ARE YOU SURE CY/N) 7? 


. Now’s your chance to change your mind. Press (N) if you want 


to reselect your devices. If you’re sure about the devices you 
selected, press [Y]. 


The next part of the CONFIG process appears on the screen: 
CONFIG 


SeLeol TERM DESCRIPTOR 


1 = TEKMLVDG 
e = TERMLWIN 
3 Ae 5 0 
Seueew Lah. flee 


. These are Color Computer terminal I/O subroutine modules 


you can use. For a 32 character display, select 1 (TERM_ 
VDG). In order to have OS-9 windows and an 80 column dis- 
play, select 2 (TERM_WIN). 


Note: You can use TERM.WIN with a TV rather than 
a monitor but it is difficult, if not impossible, to see 
characters on an 80-column window. When you later 
create text windows, select 40-column displays. 


a 
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If you select 2 (Term_Win), CONFIG presents you with 
another menu of choices. This time, the display looks like 
this: 


CONFIG 
ARROWS - UP/DOWN/MORE/BACK 
S = SELZUNSEL Ho = HELP D = DONE 
ITEM SEL 


This list represents the pre-established windows you can 
open for use with OS-9. The next section in this chapter tells 
you how to open and use windows. For now, if you expect to 
open windows in which you can run mulitple tasks, select 
these items for your new diskette. (See “Using Windows” 
later in this Chapter.) 


. After you select the modules you want to use, press (D). As it 


did when you selected devices, the screen asks ARE YOU 
SURE CY/N) ? Press if you’re finished. Or, press (N} to 
keep working on this screen. 


OS-9 creates a file called Bootlist in Drive /D0’s ROOT 
directory, using the information you’ve provided so far. It lets 
you know what it’s up to by displaying: 


BUILDING BOOT List 
PLEASE WALT 


Then, the screen asks: 


SELECT CLOCK MODULE: 
1 - 68 HZ CAMERICAN POWER) 
2 - 5@ HZ CEUROPEAN POWER) 

SELECTION 11,21 


Press if you live in the United States, Canada, or any 
other country that uses 60Hz electrical power. If you live in 
a country that uses 50Hz electrical power, press (2). 


11. 


12. 
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CONFIG is ready to begin creating your customized System 
Master diskette. If you have one drive, the screen tells you 
that the DESTINATION diskette is your blank, formatted 
diskette and that your SOURCE diskette is the BASIC09/ 
CONFIG diskette. Place your formatted diskette in the drive, 
and press (C}. You'll swap between the formatted diskette 
and the BASICO9/CONFIG diskette several times. 


If you have a two-drive system, place a formatted diskette in 
Drive /D1, and press the space bar. The screen tells you that 
OS-9 is: 


GENERATING NEW BOOT 
. PLEASE WAIT 


Following the boot file generation, a menu lets you select the 
commands you want to include on your system diskette. You 
have the following choices: none; the full set of commands; or 
a set consisting of commands you choose individually. The 
menu looks like this: 


CONFIG 


DO YOU WISH TO ADD 
[NJO COMMANDS, STOP NOW 
CFJULL COMMAND SET 
CIIJINDIVIDUALLY SELECT 
CA. RECETVE HELP 
SELECTION NGF y igh] 


Most people like to choose the individual commands they 
want to use. For the time being, press (F) to include the full 
set. Later, you can create another custom diskette that has 
only the commands you need. 
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13. Do one of the following: 


a. If you have one drive, the screen asks you to place your 


formatted diskette in Drive /D0O. Do so, and press the Wy 


space bar. Next, you’ll place your “uncustomized” backup 
of the System Master diskette in Drive /DO. Swap the two 
diskettes as the screen asks you to. When the CONFIG 
program finishes, the 059: message reappears. You now 
have a brand new, customized copy of the System Master 
diskette. 


b. If you have more than one drive, the screen asks you to 
place your system diskette in Drive /D0. CONFIG contin- 
ues and in a few minutes, finishes its work. The 0S9: 
message reappears, and you have a customized copy of the 
System Master diskette in Drive /D1. 


14. Label the diskette so that you can distinguish between your 
working copy of the System Master diskette and the custom 


copy. 


Monitor Types J 


OS-9 lets you set your system for different monitor types. The 
monitor options are for a RGB color monitor, a composite color 
monitor or TV, or a monochrome monitor or TV. To set your sys- 
tem for a particular monitor type, enter one of the following com- 
mands, or add it to your system Startup file: 


Monitor Type Command 
RGB montype r 
Composite montype c 
Monochrome montype m 


Therefore, to set your system for a composite monitor, type: 


montype c | ENTER 


To save typing the command each time you start OS-9, put it in 
the Startup file in the ROOT directory of your system diskette. 


If your system disk does not have an existing Startup file: ww 
Create one by typing: 


build startup (ENTER 
montype r 
ENTER 
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If your system disk already has a Startup file: 
First rename the Startup file by typing: 
rename startup oldstart 


Then create a file that contains the new command, such as: 


build newstart | ENTER 
montype r (ENTER 
ENTER 


Now combine the two files into a new Startup file: 


merge oldstart newstart > startup [ENTER] 


Use DEL to delete oldstart, newstart, or both, or leave them on 
your disk for future use. 


Using Windows 


If the window descriptors (W, W1, W2, W3, W4, W5, W6, W7) 
and the graphics interface and driver, GrfInt and GrfDrv, are in 
memory, OS-9 lets you set up windows on your display screen. , 


Note: GrfInt and the window descriptors must be loaded as 
part of the boot operation. Your System Master diskette does 
this. 


Once you have initialized windows, you can then move among 
them, initiating different tasks in each. You can even have differ- 
ent processes showing on different portions of your display screen 
at the same time. 


Another advantage of using windows is that you can choose win- 
dows that give you displays of 40 or 80 columns across the screen, 
rather than only 32. However, unless you have a monitor con- 
nected to your computer, rather than a television, you might be 
unable to read the screen. 


Establishing a Window 


You can establish one or more windows after booting OS-9, or you 
can include the window creation process in OS-9’s Startup file. 
Startup is a file containing commands you want your system to 
execute during startup. 
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To establish a window from the OS-9 prompt, type: 


iniz wnumber | ENTER 
shell i=/wnumbers& | ENTER 


In this example, number represents the window number to ini- 
tialize. After you type these commands, you can select the win- 
dow by pressing (CLEAR]. To return to the original screen, press 
again. 


The default values for the window descriptors /W1 through /W7 
are: 


Window Text size | Window’s physical size 

device name incolumns Starts at: Size: 
/W1 40 0,0 Dek 
/W2 40 28,0 | ae 
/W3 40 0,12 40,12 
/W4 80 0,0 60,11 
/W5 80 60,0 19,11 
/W6 80 80,0 80,12 
/W7 80 0,0 80,24 


Note: To initialize Windows /W2 and /W3, you must 
be operating from Window /W1. To create Windows 
/W5 and /W6, you must be operating from Window 
/WA4. 


The “Starts at” column, indicates the position on the screen of the 
top left corner of the window. On the screen grid, coordinates 0,0 
are located at the top left corner. 


The “Size:” column indicates the number of characters across each 
window and the number of character lines in each window. 


Therefore, Window 1 displays 40 column text, begins in the top 
left corner of the screen, extends right for 27 characters and down 
for 11 lines. Window 5 displays 80 column text, begins at the top 
of the screen, 60 columns from the left, extends 19 columns to the 
right and 11 lines down. 


Note that the coordinates for each window are based on the text 
size of the screen. Therefore, Window 1 (based on 40 column text) 
ends at column 27, while Window 5 (based on 80 column text) 
begins at column 60. 
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Using the information in the previous chart, you can now estab- 
lish any, or all, of the seven windows. 


Note: You cannot establish all of the windows unless your 
computer has 512 kilobytes of memory. 


For instance, to set up a full screen, 80-column window, type: 


shell i=/w7& 
After a short pause, the screen displays a message, such as: 
& 004 


This means that OS-9 has opened a path to your new window and 
started a shell on the window with the process identification of 04. 
To move to the window, press (CLEAR). Your 32-column screen van- 
ishes and you are now in Window 7. You can type commands or 
run programs from here in the same manner as before. 


To set up three windows on the same screen, type these com- 
mands, then use [CLEAR] to move among the windows: 


iniz wit w2 w2 (ENTER] 
shell i=/w1& (ENTER |] 
shell i=/w2& (ENTER ] 
shell i=/w3& (ENTER) 


If you want, and your computer has enough memory, you can run 
different processes in all of the windows. 


Changing Window Colors 


Perhaps you don’t like the color of the screen in one or more of 
your windows. You can change it using the display command. The 
following charts show you all of the colors available for the screen 
background, text, and border. 
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Background Code = 33 
Text Code = 32 
Border Code = 34 


Color Codes 


Codes Color 

00 or 08 White 
01 or 09 Blue 

02 or OA Black 
03 or OB Green 
04 or OC Red 

05 or OD Yellow 
06 or OE Magenta 
07 or OF Cyan 


To change a color, type DISPLAY 1b, followed by the background, 
text, border, or foreground code followed by a color code. Then, 


press (ENTER). 


For instance, if you are in Window 7, you can change the back- 
ground color to red, by typing: 


display 1b 33 04 

Change the text color to black by typing: 
display 1b 32 @2 

To put a white border around the screen, type: 
display 1b 34 @o 

You can also type all the codes on one line, like this: 
display 1b 33 04 1b 32 @2 1b 34 QO 


Pick the colors you want for each window, and change them 
using DISPLAY. | 


Eliminating a Window 


In the command to establish windows (shell i=/wnumber&), “i” 
tells SHELL that the process being created is immortal. This 
means that you can only terminate it from the window in which 
it resides. 
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To kill a window in which you have established a shell, press 
until the window you want appears on the screen. Type: 


ex (ENTER) 


Now press to move to another window in which a shell is 
running. Then use DEINIZ to deinitialize that window. For 
instance, if the window you want to eliminate is Window 1, type: 


deiniz wt | ENTER 


Using Startup To Establish A Window 


If you intend to use a window whenever you start OS-9, for 
instance if you want to use an 80 column screen, put the appro- 
priate commands in the Startup file. This file must be located in 
the ROOT directory of your system disk. 


If your system diskette already has a Startup file: 
First rename the existing Startup file, such as: 


rename startup oldstart 


Then put your new commands into a temporary file. To initialize 
window Number 7 (80 columns, full screen) with white text on a 
black background, type: 


build tempstart 
iniz w/ 


shell i=/w7& (ENTER ] 
display 1b 32 60 1b 33 82 1b 34 2 Bc > /w7 [ENTER] 


Now combine your new commands with the original Startup file 
by typing: 


merge oldstart tempstart > startup (ENTER) 


You can remove the Tempstart file by typing del tempstart 
(ENTER ], or you can leave it in your ROOT directory for future use. 
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If Startup does not already exist: 
Create it by typing: 


build startup (ENTER | 
iniz w7 (ENTER] 
display 1b 32 00 1b 33 02 1b 34 02 Oc > /w7 (ENTER) 


shell i=/w/7& | ENTER 
ENTER 


Now, after you boot OS-9, press to operate in an 80- 
column, black and white screen. 
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Chapter 1 


Introduction 


Getting Started With OS-9 contains the information you must 
know to use the system. However, the handbook reveals only a 
small part of OS-9’s capabilities. To learn about all of its fea- 
tures, you need to know more about how OS-9 works. This intro- 
duction provides such basic background information. 


The Kernel 


At the center of the OS-9 system is a module (program) called a 
kernel. (See the following illustration.) The kernel provides basic 
system services, such as multitasking and memory management. 
It links other system modules and serves as the system adminis- 
trator, supervisor, and resource manager. 


Pipe File Manage! 
PIPER 


Figure 1 
Term is your keyboard and video. 
T1 and T2 are additional terminals. 
P is a printer. 
M1, M2, and M3 are modems. 


1-1 


OS-9 Commands Reference 


The Input/Output Manager 


Although the kernel manages OS-9, it does not directly process 
the input and output of data among the other modules and your 
computer hardware (printers, disk drives, terminals, and so on). 
Instead the kernel passes this responsibility to the input/output 
manager, IOMAN. 


IOMAN has three submanagers: a character file manager, a pipe 
file manager, and a disk file manager. The responsibilities of 
these managers are as follows: 


The Character Handles the transfer of data between OS-9 

File Manager and character devices (devices that operate 
on a character-by-character basis, such as 
terminals, printers, or modems). The 
sequential character file manager (SCF) can 
handle any number or type of such devices. 


The Pipe File Handles communication between processes 
Manager or tasks. Pipes let you use the output of one 
process as the input of another process. 


The Disk File This Random Block File Manager (RBF) 

Manager handles the transfer of data to and from 
block-oriented, random access devices, such 
as a disk drive system. 


Device Drivers 


CC3IO, PIPER, and CC3DISK are device drivers. These files con- 
tain code that transforms standard data into a form acceptable 
to a particular device, whether it is a terminal, printer, modem, 
disk drive, any other device, or another file. PIPES transfers 
data between processes. 


Device Descriptors 


Term, T1, P, M1, DO, and so on, are device descriptors. These 
files describe the devices connected to the system. They contain 
device initialization data as well as code that directs OS-9 to the 
physical addresses of the ports to which devices are connected. 
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The Shell 


The kernel, in conjunction with IOMAN and its associated man- 
agers and modules, make up the OS-9 operating system. These 
modules handle all of the system’s functions. However, OS-9 
needs directions before it can accomplish useful tasks. 


Directions to the system have two sources: commands and appli- 
cations or computer language programs. 


Before commands are useful to the kernel, the shell must inter- 
pret them. It analyzes commands and converts them into code 
that the kernel can understand. 


Some application programs and computer languages also use the 
shell’s functions. Others can access the kernel directly and do not 
need to go through the shell. 


Going On 


Chapters 2 through 5 contain detailed information on the opera- 
tion of the OS-9 system illustrated in Figure 1. These chapters 
more fully describe the composition of files and directories. They 
tell about advanced features of commands and of the shell and 
contain information on multiprogramming and memory 
management. 


Chapter 6 contains descriptions of the OS-9 commands. Chapter 
7 tells you how to use OS-9’s Macro Text Editor. 
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The OS-9 File System 


Input and output refer to the data your computer system 
receives and the data that it sends. OS-9 can receive (input) 
data from a keyboard, disk files, modems, and other terminals. It 
can send (output) data to all of these devices—except the key- 
board—and to a video display. 


OS-9 receives and sends data in the same format, regardless of 
whether the destination is a file or a device. It overcomes the dif- 
ferences in the devices by defining a standard for them and using 
device drivers to make each device conform to the standard. The 
result: a much simpler and more versatile input/output system. 


Input/Output Paths 


The base of OS-9’s unified I/O system is an organization of 
paths. Input/output paths are, in effect, software links between 
files. (Remember, OS-9 thinks of all devices as files.) 


Individual device drivers process data so that it conforms to the 
hardware requirements of the device involved. Data transfer is in 
streams of 8-bit bytes that can be either bidirectional (read/ 
write) or unidirectional (read only or write only), depending on 
the device, how you establish the path, or both. A byte is a unit 
of computer data. (A byte may contain the code for one alphabet 
character.) A bit is a binary digit and has a value of either 0 or 
ie 


OS-9 does not require the data it manages to have any special 
format or meaning. The meaning of the data is determined by 
the programs that use it. 


Some of the advantages of such a unified I/O system are: 


@ Programs operate correctly regardless of the I/O devices 
selected. 


e Programs are highly portable from one computer to 
another, even when the computers have different types of 
I/O devices. 


@® You can redirect I/O to alternate files or devices when 
you run a program, without having to alter the program. 
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@ You can easily create and install new or special device 
driver routines. 


Disk Directories 


A directory is a storage place for other directories and files. It 
contains the information about the directories and files assigned 
to it so that OS-9 can easily find and access the data they 
contain. 


Each disk has its own directory system. For example, a typical 
system diskette, diagrammed partially and simply, might look 
like this: 


DO (Drive /DO) 


) 


/DO ROOT Directory 


SYS Startup CMDS 
Errmsg 
copy list dir del format 


The ROOT directory of /DO—the ROOT from which the rest of 
the disk’s file system grows—contains a file called Startup and 
two directories, SYS and CMDS. 


SYS and CMDS, in turn, contain files: SYS contains Errmsg, 
and CMDS contains Copy, List, Dir, Del, and Format. All these 
files and directories, and many more, come built into the OS-9 
system. 


OS-9 organizes each directory area into 32-byte records. The 
first 29 bytes contain filename characters. The first byte of the 
name has its sign bit (the leftmost or most significant bit) set. 
When you delete a file, it is not immediately destroyed. Rather, 
the deletion process sets the first character position of the record 
to zero, and OS-9 no longer recognizes the record. Although the 
file contents still exist, they are no longer accessible to you or 
OS-9. Subsequent file creations overwrite deleted records. 
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The last three bytes of a record make up a 24-bit binary number 
that is the logical sector number pointing to the file descriptor 
record. Logical sectors are numbered with reference to the 
sequence of their use, rather than their physical location on a 
disk. See “Disk Files” for more information on disk organization. 


You create directories using the MAKDIR command and can 
identify them by the D (directory) attribute. (See “Examining 
and Changing File Attributes”.) MAKDIR initializes each direc- 
tory with two entries having the names “.” and “..”. These 
entries contain the logical sector numbers of the directory and 
its parent directory, respectively. 


You cannot use the COPY and LIST commands (as described in 
Getting Started With OS-9) with directories. Instead, use DSAVE 
and DIR. 


You cannot delete directories directly. You must first empty a 
directory of files, convert it into a standard file, and then delete 
it. However, the DELDIR command performs all these functions 
automatically. 


Subdirectories 


A subdirectory is a directory residing in another directory. 
Actually, all directories you create are subdirectories, since all 
directories branch from the ROOT directory. However, because 
the system automatically creates the ROOT directory when you 
format a disk, this manual does not consider directories residing 
in the ROOT directory to be subdirectories. 


Subdirectories can contain files and other subdirectories. In 
effect, OS-9 catalogues files and directories in much the same 
way that you might put files pertaining to a particular subject 
in a file cabinet drawer. With OS-9, you can have as many direc- 
tory levels as your disk storage space permits. 


Disk Files 


A disk file is a logical block of data. (Logical means that 
although the data might not actually exist in a contiguous block, 
OS-9 treats it as though it does.) A file can contain a program, 
text, a command, a computer language, or any other form of 
code. Every time you ask OS-9 to store data on a disk, you must 
specify a filename for that block of data. Both you and the sys- 
tem must then use the filename to access the data. 
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The system stores all files as an ordered sequence of 8-bit bytes. 
The file can be any size from 0 bytes to the maximum capacity 
of the storage device and can be expanded or shortened as 
desired. 


When OS-9 creates or opens a file, it establishes a file pointer for 
it. OS-9 addresses bytes within the file in the same manner it 
addresses memory, and the file pointer holds the address of the 
next byte to write or read. OS-9’s read and write functions 
always update the pointer as the system transfers data. 


This pointer function lets assembly-language programmers and 
high-level language programmers reposition the file pointer. To 
expand a file, write past the previous end of the file. Reading up 
to the last byte of a file causes the next read request to return 
an end-of-file status. 


OS-9’s file system also uses a universal organization for all I/O 
devices. This feature means that application programs can treat 
each hardware device similarly. The following section gives basic 
information about the physical file structure used by OS-9. (For 
more information, see the OS-9 Level Two Technical Reference 
manual.) 


Sectors 


The data contained in a file is stored in one or more sectors (disk 
storage units). These file sectors have both a logical and a physi- 
cal arrangement. The logical arrangement numbers the sectors 
in sequence. The physical arrangement can be in any order 
based on the actual location of a sector on a disk’s surface. For 
instance, Logical Sector 1 might be located at Physical Sector 
10, and Logical Sector 2 might be located at Physical Sector 19. 


Each sector contains 256 data bytes. The first sector of every file 
(Logical Sector Number 0 or LSN 0) is called the file descriptor. 
It contains the logical and physical description of the file. The 
disk driver module links sector numbers to physical track/sector 
numbers on a disk. 


A sector is the smallest physical unit of a file that OS-9 can 
allocate for storage. On the Color Computer, a sector is also the 
smallest file unit. (To increase efficiency on some larger-capacity 
disk systems, OS-9 uses uniform-sized groups of sectors, called 
clusters, as the smallest allocatable unit. A cluster is always an 
integral power of two—2, 4, 8, and so on.) 
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OS-9 uses one or more sectors of each disk as a bitmap (usually 
starting at LSN 1) in which each data bit corresponds to one 
cluster on the disk. The system sets and clears bits to indicate 
which clusters it is using, which clusters are defective, and 
which clusters are free for allocation. The Color Computer 
default floppy disk system uses this format: 


® Double-density recording on one side 
@ 35 tracks per diskette 

@ 18 sectors per track 

@ One sector per cluster 


Each OS-9 file has a directory entry that includes the filename 
and the logical sector number of the file’s file descriptor sector. 
The file descriptor sector contains a complete description of its 
file, including: 


e Attributes 
a ° Owner 
° Date and time created 
® Size 
@ Segment list (description of data sector blocks) 


| 


Unless the file size is 0, the file uses one or more sectors/clusters 
to store data. The system groups data sectors into one or more 
adjacent blocks called segments. 


Text Files 


Text files contain variable-length lines of ASCII characters. A 
carriage return (ASCII code 0D hexadecimal or 18 decimal) ter- 
minates each line. Text files contain such data as program 
source code, procedure files, messages, and documentation. 


Programs usually read text files sequentially. Almost all high- 
level languages (such as BASICO9) support text files. 


Use LIST to examine the content of text files. 
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Random-Access Data Files 


Random-access files consist of sequences of records, with each 
record the same length. A program can find any record’s begin- 
ning address by multiplying the record number by the number of 
bytes used for each record. This feature allows direct access of 
any record. 


Usually, high-level languages let you subdivide records into 
fields. Each field can have a fixed length and use. For example, 
the first field of a record can be 25 text characters in length, the 
next field can be two bytes in length and used to hold 16-bit 
binary numbers, and so on. 


OS-9 does not directly process records. It only provides the basic 
file functions used by high-level languages to create and handle 
random-access files. 


Programmers use high-level languages like BASICO9, Pascal, 
and C to create random-access data files. For instance, in 
BASICO9 and Pascal, GET, PUT, and SEEK functions operate 
on random-access files. 


Procedure Files 


Procedure files are disk files that contain commands. You can 
use them to execute a series of commands by typing and enter- 
ing a single command name. 


Your System Master diskette contains one procedure file named 
Startup. You can create your own procedure files using the 
BUILD command, copying input from the keyboard to a file, or 
by using a text editor program. For instance, suppose you have 
three disk drives, /DO, /D1, and /HO. You could create three very 
simple procedures to allow you to look at the directories of these 
disks by typing and entering a simple two-character command. 


To create a procedure file to look at the directory of /D1, type: 


build p1 
display @C [ENTER] 
dir /d1 

display QA [ENTER] 
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The first line creates a file named P1 (print directory for Drive 
/D1). When you press [ENTER], a question mark appears on the 
screen telling you that OS-9 is waiting for input. Type the rest 
of the lines. Finally, press at the beginning of a line to 
tell OS-9 that the input is complete. OS-9 closes the file. 


Now, to see the contents of Drive /D1, type p1 (ENTER). The com- 
mand display @C clears the video screen. The command 
display @A causes the cursor to drop down one line on the 
screen. 


Use your imagination. Almost anything you can do from the key- 
board, you can do with a procedure file. However, remember that 
OS-9 looks only in the current data directory for a procedure 
file, unless you provide a full pathlist to the procedure. Also, 
OS-9 must be able to find any command in the current execution 
directory that is part of a procedure file. If the current execution 
directory does not contain the commands you need, change it, 
either from the keyboard or as part of your procedure file. 


Executable Program Module Files 


OS-9 program modules are executable program code, generated 
by an assembler or compiled by a high-level language. A file can 
contain one or more program modules. 


Each module has a standard format that includes the object code 
(the executable portion of the module), a module header that 
describes the type and size of the module, and a CRC (Cyclic 
Redundancy Checksum) value. The system stores program mod- 
ules in files in the same structure in which they load into mem- 
ory. Because OS-9 programs are position-independent, they do 
not require specific memory addresses for loading. 


For OS-9 to load program module(s) from a file, the file execute 
attribute must be set, and each module must have a valid mod- 
ule header and CRC value. If you or the system alters a program 
module in any way (either as a file or in memory), its CRC 
check value becomes incorrect, and OS-9 cannot load the module. 


If a file contains two or more modules, OS-9 treats them as a 
group and assigns contiguous memory locations for them. 
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Using LIST on program files or any other files that contain 
binary data, causes a jumbled display of random characters and 
an error message. 


Miscellaneous File Use 


OS-9’s basic file functions are so versatile that you can devise 
almost unlimited numbers of special-purpose file formats for 
particular applications that require formats not discussed here 
(text, random-access, and so on). 


The File Security System 


Each file and directory has properties called ownership and attri- 
butes that determine who can access the file and how they can 
use it. 


OS-9 automatically stores the user number associated with the 
creation of a file. The system considers the owner of the number 
to be the owner of the file. 


Security functions are based on access attributes. There are 
eight attributes, each of which can be turned off or on indepen- 
dently. When the D (directory) attribute is on for a file, that file 
is a directory. (Only MAKDIR can set the D attribute for a file.) 
When the S (single-user) attribute is on, only one program or 
user can access the file at a time. 
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The other six attributes control whether the file can be read 
from, written to, or executed by either the owner or the public 
(all other users.) When on, these six attributes function as 


follows: 


Owner read 
permission 


Owner write 
permission 


Owner execute 
permission 


The owner can read from the file. Use this 
permission to prevent binary files from 
being used as text files. 


The owner can write to the file or delete it. 
Use this permission to protect important 
files from accidental deletion or 
modification. 


The owner can load the file into memory 
and execute it. To be loaded, the file must 


contain one or more valid OS-9 memory 
modules. 


Public read 
permission 


Anyone can read and copy the file. 


Public write Anyone can write to or delete the file. 


permission 


Public execute Anyone can execute the file. 


permission 


For example, if a file has all permissions on except write permit 
to public and read permit to public, the owner has unrestricted 
access to the file. Other users can execute it but cannot read, 
copy, delete, or alter it. 


Examining and Changing File Attributes 


You can use the DIR command, with the E (entire) option, to 
examine the security permissions of all files in a particular 
directory. An example of output using DIR E on the current data 
directory is: 


Directory of 10:20:44 


Owner Last modified Attributes Sector Bytecount Name 


6567 OS9Boot 


O° BOs E Fi3) 1436. SH SSapeeP e 

0 86/07/31 1437 d-ewrewr 71 S60 CMDS 

0 86/07/31 1442 d-ewrewr 1B8 80 SYS 

EF SBGAUT Sl aba Ser ees wr 1Bd 55 startup 
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The Attributes column shows which attributes are on by listing 
one or more of the following codes. 


Yr 
= owner read 
> owner write 


ds ew roeow 
> owner execute 


> public read 
> public write 
> public execute 
> single-user 
> directory 
For example, the first file shows: 


RRS power 


This means that (1) The file is not a directory. (2) It is share- 
able. (3) The public cannot execute it or (4) write to it, but can 
(5) read it. (6) The owner cannot execute the file, but can (7) 
write to it, and (8) can read it. 


To examine the attributes of a particular file, use ATTR. Typing 
ATTR followed by a filename shows you the file’s current attri- 
butes, for example: 


attr file2 
A possible screen display is: 
aS ae a wr 


To change a file’s attributes use ATTR and a filename, followed 
by a list of one or more attribute abbreviations. However, you 
must own a file before you can change its attributes. 
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The following command enables public write and public read per- 
missions and removes the execute permission for both the owner 
and the public: 


attr file2 pw pr -e -pe [ENTER] 


Note: In order to protect data stored in directories, the D 
attribute behaves somewhat differently from the other attri- 
butes. You cannot use ATTR to turn on the D attribute— 
only MAKDIR can do that—and you can use ATTR to turn 
off D only if the directory is empty. 


Record Lockout 


When two or more processes use the same file simultaneously, 
they might attempt to update the file at the same time, causing 
unpredictable results. When you open a file in the update mode, 
OS-9 eliminates the problem of simultaneous use by locking the 
sections of the file. The lock covers any disk sectors containing 
the bytes last read by each process accessing the file. If one pro- 
cess attempts to access a locked portion of a file, OS-9 puts the 
process to sleep until the locked area is free. 


OS-9 moves the lock and frees the area when it reads from or 
writes to another area. The system removes a lock on a file when 
the process associated with the lock closes its path to the file. A 
process can have only one lock on a file, but it can have locks on 
more than one file. 


You can lock an entire file by activating its single user bit. (See 
the earlier section “Examining and Changing File Attributes.”) 
When the single user bit is on, only one process can open a path 
to the file at a time. Attempts by other processes to access the 
file result in an error. 
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Device Names 


Each physical I/O device supported by OS-9 has a unique name. 
The following list describes some of the device names supported 
by the system. Your system diskette already contains several of 
these devices. You can define others to use with CONFIG. 


DO_35S 
D1_358S 
D2_35S 
D3_35S 
DDDO_35S 
DO_40D 
D1_40D 
D2_40D 
DDDO_40D 
D1_80D 
D2_80D 

P 

TERM 

T1 

T2 


T3 


Floppy Disk Drive /D0O, single sided, 35 
cylinders. 

Floppy Disk Drive /D1, single sided, 35 
cylinders. 

Floppy Disk Drive /D2, single sided, 35 
cylinders. 

Floppy Disk Drive /D8, single sided, 35 
cylinders. 

Default Disk Drive /DO, single sided, 35 
cylinders. 

Floppy Disk Drive /DO, double sided, 40 
cylinders. 

Floppy Disk Drive /D1, double sided, 40 


cylinders. 

Floppy Disk Drive /D2, double sided, 40 
cylinders. 

Default Disk Drive /DO, double sided, 40 
cylinders. 


Floppy Disk Drive /D1, double sided, 80 
cylinders. 

Floppy Disk Drive /D2, double sided, 80 
cylinders. 

a printer using the RS-232 serial port 

your computer keyboard and video display 

a terminal port using the standard RS-232 
port 

a terminal using the optional RS-232 
communications pak 

a terminal using the optional RS-232 
communications pak 

a modem using an optional 300 baud modem 
pak 

a modem using an optional 300 baud modem 
pak 

a generic window descriptor 

window device Number 1 
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W2 window device Number 2 
W3 window device Number 3 
W4 window device Number 4 
W5 window device Number 5 
W6 window device Number 6 
W7 window device Number 7 


Although OS-9 and your computer can access all these devices, 
your original diskette does not configure it to do so. For informa- 
tion on configuring your system, see Chapter 7 of Getting 
Started With OS-9. 


Because device names are at the root of the file system, you can 
use them only as the first part of a pathlist. Always precede the 
name of a device with a slash. 


When you refer to a non-disk device, for example a terminal or 
printer, use only the device name. /P, for instance, is the full 
allowable pathlist for a printer. 


Note: An I/O device name is actually the name of an OS-9 
device descriptor that you precede with a slash (/). OS-9 
automatically loads device descriptors during the OS-9 boot 
sequence. You can add or delete other device descriptors 
while the system is running or add device descriptors to the 
bootfile using CONFIG. 
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Advanced Features of the Shell 


This chapter discusses the advanced capabilities of the shell. In 
addition to basic command line processing, the shell facilitates: 


@ Input/output redirection, including filters 


@ Memory allocation 


Multitasking (concurrent execution) 
@e Procedure file execution 
@ Built-in commands 


You can use these advanced capabilities in many combinations. 
Following are several examples. Study the basic rules, use your 
imagination, and explore. 


More About Command Line Processing 


The shell is a program that reads and processes command lines, 
one at a time, from the computer’s input device (usually your 
keyboard). It parses (scans) each line to identify and process any 
of the following parts that might be present: 


e A program, procedure file, or built-in command 
@ Parameters to be passed to the program 
@ Execution modifiers to be processed by the shell 


For some commands, only the keyword (the program, procedure 
file, or command name) must be present. Other commands have 
required or optional parameters. As well, a command line can 
include modifiers that influence the operation of the command. 
OS-9 features that affect command execution are: 


Execution Let you increase the amount of random access 

Modifiers memory (RAM) available for a command. Also 
lets you redirect input to a process, output from 
a process, or both. 


Command Let you enter more than one command on a line, 

Separators perform concurrent execution of commands, or 
connect the input or output of one command to 
another command. 
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Command Lets you group all the commands that you want 
Grouping affected by command modifiers or separators. 


Note: The next section, “Command Modifiers,” provides 
details on these features. 


Once the shell identifies the keyword, it processes any modifiers. 
It then assumes the remaining text consists of parameters, 
which it passes to the program being called. 


When the shell receives a built-in command, it immediately exe- 
cutes it. If it receives a command that is not built in, it searches 
for the appropriate program and then runs it as a new process. 
The keyword must be the first entry in any line. 


While the program is running, the shell deactivates itself. At the 
termination of the program, the shell reactivates and accepts the 
next input. This cycle continues until the shell detects an end-of- 
file in the input path. It then terminates its own execution. You 
can input an end of file from the keyboard by pressing 


(SHIFT J[_BREAK . 


Following is a sample shell command line that calls the 
assembler. 


In this example: 
ASM is the keyword. 


sourcefile, 1, and -o are the 
parameters passed _ to 
ASM. 

>/P is a modifier that 
redirects the output (the 
listing) to the system’s 
printer. 

#12k is a modifier that 
asks the system to assign 
12K bytes of memory 
instead of a smaller default 
amount 


[1d ak =o] 


asm sourcefile 1 -o >/p #12k 


en 
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Command Modifiers 


Add command modifiers to a command line to change the way in 
which the command functions. Modifiers let you tailor OS-9 com- 
mands to your specifications. Type them in a command line after 
the keyword and either before or after other parameters you 
might be using. 


The shell processes command modifiers before it executes a pro- 
gram. If it detects an error in any of the modifiers, it stops exe- 
cution and reports the error. 


The shell strips command modifiers from the part(s) of the com- 
mand line passed to the program as parameters. Therefore, you 
cannot use the characters reserved as modifiers (#;!< > & ) 
inside other parameters. 


Execution Modifiers 


Execution modifiers alter the amount of memory commands have 
available, or they redirect command input or output. 


Alternate Memory Size Modifier. When the shell invokes a 
command program, it allocates the minimum amount of working 
RAM (random access memory) specified in the program’s module 
header. 


Note: All executable programs include a module header 
which holds the program’s name, size, memory require- 
ments, and other information. For information on viewing 
the contents of a module header, see the IDENT command. 


You might want to increase a command’s default memory size. 
You can assign memory either in 256-byte pages or in 1024-byte 
increments. To add memory in pages, use the modifier #n, where 
n is the number of pages. To add memory in 1024-byte incre- 
ments, use the modifier #nK, where n is the number of 1024- 
byte increments. 


The following two examples have identical results: 


copy #8 file1 file2 (8x 256 = 2048 bytes) 
copy #2K file1l file2 (2 x 1024 = 2048 bytes) 
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V/O Redirection Modifiers. Input/output redirection modifiers 
reroute a program’s I/O from the standard path to alternate files 
or devices. 


One of OS-9’s advantages is that its programs use standard I/O 
paths rather than individual, specific file, or device names. You 
can easily redirect the I/O to any file or device without altering 
the program itself. 


Programs that normally receive input from a terminal or send 
output to a terminal use one or more of these three standard I/O 
paths: 


e Standard input path—Routes data from the terminal’s 
keyboard to programs. The standard input path is Path 
Number 0. 


Use the less-than symbol (<) to redirect data to this 
path. 


e Standard output path—Routes data from programs to 
the terminal’s display. The standard output path is Path 
Number 1. 


Use the greater-than symbol (>) to redirect data from 
this path. 


e Standard error output path—Routes routine status 
messages (prompts and errors) to the terminal’s display. 
(The name error output path is somewhat misleading, 
since many kinds of messages in addition to error mes- 
sages travel the path.) The standard error path is Path 
Number 2. 


Use two greater-than symbols (>>) to redirect data 
from this path. 


When you use a redirection modifier in a command line, follow it 
immediately with a pathlist for the substitute device. For exam- 
ple, you can use LIST to redirect the contents of a file called 
Correspondence from the terminal to the printer, by typing: 


list correspondence >/p (ENTER 


The shell automatically creates, opens, and closes files referenced 
by redirection modifiers as needed. The system immediately 
restores normal I/O paths at the completion of any com- 
mand using redirection modifiers. 
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In the next example, the shell redirects DIR’s output—a list of 
files in the MEMOS directory—to the file /D1/Savelisting: 


dir /d@/memos >/d1/savelisting 


You can now view the contents of Savelisting by typing: 


list /d1/savelisting 


OS-9 displays the file contents in a format similar to a directory 
listing. 


Directory of /d@/memos 
CMDS =e startup 
OS9Boot 


You can use one or more redirection modifiers before the pro- 
gram’s parameters, after the program’s parameters, or both. 
However, use each modifier only once in a command. 


The following example shows how you can use all of the redirec- 
tion modifiers together to start BASICO9 on a device window and 
redirect all input and output to it: 


basic@9 <>>>/wi1 | ENTER 


When you redirect multiple paths, you must use the redirection 
symbols in the proper order as shown here: 


Legal Illegal 
eT |. >< fwl 
<<>> [wl >>< /wl 
>>> /wl =>< fowl 


Command Separators. You can include more than one com- 
mand on a command line by using command separators. Com- 
mand separators cause multiple commands to execute either 
sequentially or concurrently, depending on the separator you 
use. 


Sequential execution means that one program must complete its 
function and terminate before the shell lets the next program 
execute. Concurrent execution means that two or more programs 
begin execution and run simultaneously. 
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Sequential Execution Using the Semicolon. Using a semi- 
colon between commands on one line causes them to execute 
sequentially. For instance: 


eopy myfile /dl¢newfiles dir >/p (ENTER ] 


This command causes the shell to: (1) execute the COPY com- 
mand, (2) enter a waiting state until COPY terminates, then 
awake, and (3) execute DIR. 


If an error occurs in any program, the shell does not execute 
subsequent commands, regardless of the state of the SHELL 
command’s X (stop on error) option. 


Here are two more examples of commands using the semicolon: 


copy clafilie newrites del oldfile; list newfile 


dir /di/myfile; list temp >/p; del temp (ENTER] 


Commands separated by semicolons are in fact separate and 
equal child processes of the shell. 


Note: When one process creates another process, OS-9 calls 
the creator the parent process and the created process the 
child process. The child can become a parent by creating 
yet another process. 


Concurrent Execution Using the Ampersand. You can use 
the ampersand (&) to cause multiple commands to run at the 
same time. Each command you specify runs as a separate child 
process of the shell. That is, for each process, the shell creates a 
separate shell to handle the operation. When the process is com- 
plete, the child shell terminates, or dies. 


While more than one process is running, OS-9 divides execution 
time equally among the processes. 


The number of programs that can run at the same time varies. 
It depends on the amount of free memory in the system and the 
memory requirements of the programs being executed. 


An example of a simple command line using the & separator is: 


dir >/p& (ENTER 
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The shell begins to run DIR, sending output to the printer. At 
the same time it displays both the number of the forked process 
(DIR) and a new prompt, like this: 


&807 
O$S9: 


To fork a process means to create a process as a branch of 
another process—a subroutine. 


After using the ampersand to fork a background process, you 
can then enter another command, which the shell executes while 
output from your original command continues to go to the 
printer. This means you don’t waste time waiting for OS-9 to fin- 
ish a task. At times, the keyboard might not seem to respond to 
your typing, because characters do not appear on the screen. 
However, OS-9 stores the characters in the keyboard buffer and 
displays them as soon as the shell can accept input again. 


If you have several processes running simultaneously and want 
information about them, use the PROCS command. 


Combining Sequential and Concurrent Executions. You can, 
if you want, use both the concurrent and sequential command 
separators in one command line. For example: 


dir >/p& list fileté copy Titel Filecs del’ Temp 


Because the & modifier joins the DIR, LIST, and COPY com- 
mands, these commands run concurrently. But, because a semi- 
colon precedes the DEL command, DEL does not run until the 
other commands terminate. 


Using Pipes: The Exclamation Mark. You can use the excla- 
mation mark (!) to construct pipelines for OS-9 commands. Pipe- 
lines consist of two or more concurrently executing programs 
with standard input paths, and standard output paths or both, 
connected to each other with pipes. 


Pipes are the primary means of transferring data from process 
to process. They are vital to interprocess communications. Pipes 
are first-in, first-out buffers, or holding areas for data. 
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The shell automatically buffers and synchronizes I/O transfers 
using pipes. A single pipe can direct data to several destinations 
or readers, and can receive data from several sources, or writers 
on a first-come, first-serve basis. An end-of-file occurs if a pro- 
gram attempts to read from a pipe when writers are not avail- 
able to send data. Conversely, a write error occurs if a program 
attempts to write to a pipe when readers are not available. 


Pipelines are created by the shell when it processes an input line 
with one or more pipe separators (!). For each pipe separator, the 
shell directs the standard output of the program on the left of 
the pipe separator to the standard input of the program on the 
right of the separator. The shell creates an individual pipe for 
each pipe separator in the command line. For example: 


ipndate <master—_tile £ sort 1 write_report 


>/p (ENTER 


This command redirects input from a path called Master_file to 
a file named Update. The output of Update becomes the input for 
the program Sort. The output of Sort, in turn, becomes the input 
for the program Write_report. Finally, the command redirects 
output from Write_report to the printer. The shell executes all 
programs in a pipeline concurrently. The pipes synchronize the 
programs so the output of one never gets ahead of the input 
request of the next program. This synchronization means that 
data cannot flow through a pipeline any faster than the slowest 
program can process it. 


Raw Disk Input/Output. OS-9 has a special pathlist function 
to perform raw physical input/output operations on a disk. The 
pathlist consists of the device name, immediately followed by the 
“@” character. 


This command causes OS-9 to treat the entire diskette in Drive 
/DO as one logical file. The operation reads each byte of each sec- 
tor, without regard to actual file structure. Commands such as 
DIR, ATTR, and MFREE use this feature to access sectors of 
disks that are not part of file data areas, such as header sectors. 


Warning: When using this raw access, use extreme cau- 
tion. Because you can write on any sector, you can easily 
damage file or directory structures and lose data. Using @ 
defeats any file security and record locking systems. 
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To convert a byte address to a logical sector number when using 
@, multiply the sector number by 256. Conversely, the logical 
sector number of a byte address is the byte address, modulo 256. 


Command Grouping 


You can enclose sections of command lines in parentheses to per- 
mit modifiers and separators to affect an entire set of programs. 
The shell processes the material in the parentheses by recur- 
sively calling itself to execute the enclosed command list. 


For example, if you want to send directory listings of the ROOT 
directory of Drive /DO and then the ROOT directory of Drive /D1 
to the printer, you can type either: 


dir /d®@ >/p; dir /d1 >/p [ENTER] 


or: 


Cdir /d@; dir /d1) >/p (ENTER) 


The results are identical except that the system keeps the printer 
continuously in the second example. In the first example, another 
user could steal the printer between DIR commands. 


You can group commands to cause programs to execute both 
sequentially and concurrently with respect to the shell that ini- 
tiated them. For instance: 


Cdel filet; del file2; del file3)& [ENTER] 


Here, the shell does the overall deleting process concurrently 
with whatever else you tell it to do, because you’re using &. 
However, the shell deletes the three specified files sequentially 
because you’re using semicolons within the parentheses. 


Suppose you have a program named Makeuppercase that con- 
verts lowercase characters to uppercase and a program named 
Transmit that sends data to another computer, you can use a 
command line like this: 


Cdir cmds; dir sys) ! makeuppercase ! transmit 


The shell processes the output of the first DIR command and 
then the second. It sends all the DIR output to Makeuppercase, 
and Transmit sends all the output to another computer. 
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Shell Procedure Files 


The shell is a re-entrant program. This means it can be simulta- 
neously executed by more than one process. Like most other OS- 
9 programs, the shell uses standard I/O paths for routine input 
and output. 


OS-9’s shell offers you a special feature, a time and effort saver 
called a procedure file. A procedure file is a related group of 
commands, and when you run the file, you execute all the 
commands. 


Other names for procedure file processing are batch and back- 
ground processing. A procedure file becomes new input for the 
shell. By running a procedure file, you’re using the shell to cre- 
ate a new shell, a subshell that accepts and carries out the com- 
mands in the procedure file. 


Note: If you plan to use the same command sequences 
repeatedly, create a procedure file to do the job by using 
BUILD. 


When you enter any command line, the shell looks for the speci- 
fied program in memory or in the execution directory. If it can- 
not find the program there, it searches the data directory for a 
file with the specified name. If it finds the file, the shell auto- 
matically interprets it as a procedure file, and creates the sub- 
shell, which executes the commands listed in the procedure file. 


Procedure files can also let the computer execute a lengthy 
series of programs while it is unattended, or even while it is run- 
ning other programs. 


There are two ways to run a procedure file. For instance, to exe- 
cute a procedure file called Mailsequence, type either: 


shell mailsequence [ENTER 


or 


mailsequence [ENTER 


Both commands do the same thing: create a subshell to run the 
commands you’ve built into your Mailsequence procedure file. 


To run a procedure file in a concurrent mode, use the ampersand 
(&) modifier. As long as memory is available, you can run any 
number of files concurrently. 
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You can even build procedure files to sequentially or concurrently 
execute other procedure files. 


Note: If you use procedure files to run programs you don’t 
intend to monitor closely, you can redirect standard output 
and standard error output to another file. Later you can 
review the file’s contents. Output redirection eliminates the 
annoying output of shell messages on your terminal at ran- 
dom times. 


Built-in Shell Commands and Options 


The shell has a number of built-in commands and options. 
Whenever you use one of these functions, the shell executes it 
without loading it or creating a new process to execute it. 


You can execute built-in functions alone, use them at the begin- 
ning of a command line, or use them following any program sep- 
arator. You can separate adjacent built-in commands by spaces 
or commas. 


The built-in commands and their functions are: 


CHD pathlist Changes the data directory to the directory 
specified by the pathlist. 


CHX pathlist Changes the execution directory to the direc- 
tory specified by the pathlist. 


EX modname Directly executes the module named. This 
function deletes the shell process so that it 
ceases to exist and executes the new module in 
its place. Use EX to replace the executing 
shell with the program specified by modname. 
You can also use EX without a module name 
to eliminate the current shell, for example, a 
shell you initialized in a window (see below). 


i= devname Makes a shell an immortal shell. This means 
that when the shell ends, due to an EOF, OS-9 
restarts it. Each time the shell restarts, it has 
the same data and execution directories. To 
kill an immortal shell, use EX to “chain” to a 
null process, such as: 


ex CENTER } 
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* text 


kill procID 


setpr procID 
number 


x 


-X 


“p 


-t 


Waits for any process to terminate. 


Allows you to make a comment. The shell does 
not process text following the asterisk. Use 
this function to label operations in a procedure 
file. 


Stops the specified process. 


Changes the specified process’s priority 
number. 


Causes the shell to cease operation whenever 
an error occurs (a system default). 


Causes the shell to continue operation when 
an error occurs. Use this function in procedure 
files to enable the shell to continue to other 
commands if one command process fails 
because of a system error. 


Turns the shell prompt and messages on (a 
system default). 


Inhibits the shell prompt and messages. Use 
this option in procedure files to disable screen 
display. Be sure to turn the prompt and mes- 
sage function back on afterward. 


Makes the shell copy all input lines to output. 
Use this function with a procedure file to 
cause command lines to display as they 
execute. 


Sets the system so that it does not copy input 
lines to output (a system default). 


Running Compiled Intermediate 
Code Programs 


Before the shell executes a program, it checks the program mod- 
ule’s language type. If it is not 6809 machine language, the shell 
calls the appropriate run-time system for that module. 
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For instance, if you have BASICO9 on your OS-9 system and 
want to run a BASICO9 I-code module called Adventure, you can 


f ‘\ type: 
basic@9 adventure [ENTER] 


or: 


adventure | ENTER 
Or: 
| runb adventure | ENTER 


In the last example, the shell uses the RUNB module to inter- 
pret the Adventure I-code module. 
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Multiprogramming and 
Memory Management 


One of OS-9’s most valuable capabilities is multiprogramming— 
sometimes called timesharing or multitasking. This feature lets 
your computer run more than one process at the same time. 
Multiprogramming can be a time saving advantage in many sit- 
uations. For example, you can edit one program while the system 
prints another. Or you can use your Color Computer to control a 
household alarm system, lighting, and heating and at the same 
time use it for routine work or entertainment. 


OS-9 uses multiprogramming regularly for internal functions. 
You can use it by putting an ampersand at the end of a com- 
mand line. Doing this causes the shell to run your command as 
a background, or concurrent, task. 


To run several processes simultaneously, OS-9 must coordinate 
its input/output system and CPU time and allocate its memory 
as needed. This chapter gives you some basic information about 
how OS-9 manages its resources to optimize system efficiency 
and make efficient multiprogramming a reality. 


Processor Time Allocation 
and Timeslicing 


CPU time is the most precious resource of a computer. If the 
CPU is busy with one task it cannot perform another. For exam- 
ple, many processes must wait for you to enter information from 
the terminal. While the process is waiting, your computer’s CPU 
must also wait. Your computer is limited by your typing speed. 


On many systems there is no way around such a bottle neck. 
However, OS-9 is more efficient. It assigns CPU time to pro- 
cesses only as they need it. 


To do this, OS-9 uses timeslicing. Timeslicing, as described in 
the following paragraphs, lets all active processes share CPU 
time. 


A real-time clock interrupts the Color Computer’s CPU 60 times 
each second. The interruption points are called ticks, and the 
spaces between ticks are called timeslices. 
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OS-9 allocates timeslices to each process. At any tick it can sus- 
pend execution of one process and begin execution of another. 
This starting and stopping of processes does not affect their 
execution. 


How often OS-9 gives a process timeslices depends on the pro- 
cess’s priority relative to the priority of other active processes. 
You can access priority using a decimal number from 0 through 
255, where 255 is the highest priority. 


OS-9 automatically gives the shell a priority of 128. Because 
child processes inherit their parents’ priorities, the shell’s child 
processes also have priorities of 128. You can find a process’s 
priority with the PROCS command, and can change it using the 
SETPR command. 


You cannot compute the exact percentage of CPU time assigned 
to any particular process, because there are some dynamic vari- 
ables involved, such as the time the process spends waiting for 
I/O devices. But you can approximate the percentage by dividing 
the process’s priority by the sum of the priority of all active 
processes: 


process’s CPU share = priority of the process 


sum of the priorities 
of all active processes. 


Note: Timeslicing happens so quickly that it looks as if all 
processes execute simultaneously and continuously. If, how- 
ever, the computer becomes overloaded with processing, you 
might notice a delay in response to input from the termi- 
nal. Or, you might notice that a procedure program takes 
longer than usual to run. 


Process States 


The CPU time allocation system automatically assigns each pro- 
cess one of three states that describes its current status. Process 
states are important for coordinating process execution. A pro- 
cess can have only one state at any instant, although state 
changes can be frequent. The states are: 


e Active—Applies to processes currently able to work— 
that is, those not waiting for input or for anything else. 
These are the only processes assigned CPU time. 
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@ Waiting—Applies to processes that the system suspends 
until another process terminates. This state allows coor- 
dination of sequential process execution. The shell, for 
example, is in the waiting state during the execution of a 
command it has initiated. 


@ Sleeping—Applies to a process suspending itself for a 
specified time, or until receipt of a signal. (Signals are 
internal messages that coordinate concurrent processes.) 
This is the typical state of processes waiting for input/ 
output operations. 


The shell does not assign CPU time to sleeping or wait- 
ing processes. It waits until they become active. The 
PROCS command gives information about process states. 


Creation of Processes 


If a parent process creates more than one child process, the chil- 
dren are called siblings with respect to each other. If you exam- 
ine the parent/child relationship of all processes in the system, a 
hierarchical lineage becomes evident. In fact, this hierarchy 
resembles a family tree. (The family concept makes it easy to 
describe relationships between processes.) OS-9 literature uses 
the family concept extensively in describing OS-9’s multipro- 
gramming functions.) 


OS-9’s fork function automatically performs the sequence of oper- 
ations required to create a new process and initially allocate 
resources to it. 


If for any reason, fork cannot perform any part of the sequence, 
the system stops and fork sends its parent an error code. The 
most frequent reason for failure is the unavailability of required 
resources (especially memory), or the inability of the system to 
find the specified program. 


A process can create many processes, subject only to the availa- 
bility of unassigned memory. When the parent issues a fork 
request to OS-9, it must specify certain information: 


@ A primary module—The name of the program to be 
executed by the new process. The program can already 
be present in memory, or OS-9 can load it from a disk 
file with the same name. 


4-3 


OS-9 Commands Reference 


e Parameters—Data to be passed to and used by the new 


process. OS-9 copies this data to part of the child pro- 
cess’s memory area. (Parameters frequently pass file- 
names, initialization values, and other information. ) 


The new process inherits some of its parent’s properties, 
including: 


e A user number—For use by the file security system to 


identify all processes belonging to a specific user. (This 
is not the same as the process ID, which identifies a pro- 
cess.) OS-9 obtains this number from the system pass- 
word file when a user logs on. The system manager is 
always User 0. 


Standard input and output paths—The three paths: 
input, output, and error, used for routine input and out- 
put. Most paths can be shared simultaneously by two or 
more processes. 


Current directories—The data directory and the execu- 
tion directory. 


e Process priority. 


As part of the fork operation, OS-9 automatically assigns: 


Ad. 


e@ A process ID, a number in the range 1 to 255 that iden- 


tifies the process. Each process has a unique number. 


Enough memory to support the new process. In OS-9, all 
processes share a memory address. OS-9 allocates a data 
area for the process’s parameters and variables and a 
stack for each process’s use. It needs a second memory 
area in which to load the process if it does not reside in 
memory. 
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In summary, each new process has: 
e A primary module 
@ Parameters 
@ A user number 
@ Standard I/O paths 
@ Current directories 
@ A priority 
@ An ID number 


® Memory 


Basic Memory Management Functions 


Memory management is an important OS-9 function. OS-9 auto- 
matically allocates all system memory to itself and to processes, 
and also keeps track of the logical contents of memory (the pro- 
gram modules that are resident in memory at any given time). 
The result is that you seldom need to bother with the actual 
memory addresses of programs or data. 


The operating system and each process have individual address 
spaces. Each address space has the potential to contain up to 64 
kilobytes of RAM memory. Using memory management unit 
(MMU) hardware, OS-9 moves memory into and out of each 
address space as required for system operations. 


Although each unit is subject to the 64K maximum program 
size, you can run several processes simultaneously and utilize 
more than 64K overall. The system logically assigns RAM mem- 
ory in 256-byte pages, but the MMU’s hardware block size is 
8K. Each of these physical blocks has an extended address that 
is called a block number. For example, the 8K physical block 
residing at address $3C000 to $3DFFF is Block Number $3C. 


Within an address space, OS-9 assigns memory from higher 
addresses downward for program modules and from lower 
addresses upward for data areas. The following chart shows this 
organization: 
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highest address 


program modules 
(RAM or ROM) 


unused space 


(RAM or empty) 


data areas 
(RAM) 


lowest address 


Loading Program Modules into Memory 


When performing a fork operation, OS-9 first attempts to locate 
the requested program module by searching the module direc- 
tory, which has the address of every module present in memory. 
The 6809 instruction set supports a type of program called re- 
entrant code, which means that processes can share the code of a 
program simultaneously. 


Since almost all OS-9 family software is re-entrant, the system 
can make the most efficient use of memory. For example, suppose 
that OS-9 receives a request (from a process) to run BASICO9 
(which requires 22 kilobytes of memory), but has already loaded 
it into memory for another process. Because the software is re- 
entrant, OS-9 does not have to load it again and use another 
22K of memory. Instead the new process shares the original 
BASICO9 by including the location of the BASICO9 module in its 
memory map. 


OS-9 automatically keeps track of how many processes are using 
each program module, and deletes the module when all processes 
using it terminate. 


If the requested program does not yet reside in memory, OS-9 
uses its name as a pathlist (filename) and attempts to load the 
program from disk. 
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Every program module has a module header describing the pro- 
gram and its memory requirements. OS-9 uses the header to 
determine how much memory the process needs for variable stor- 
age. The module header includes other information about its pro- 
gram, and is an essential part of the OS-9 machine language 
operation. 


You can also place commands or programs into memory using 
the LOAD command. Doing so makes the program available to 
OS-9 at any time, without having to be loaded from disk. A pro- 
gram is physically loaded into memory only if it does not already 
reside there. 


LOAD causes OS-9 to copy the requested module from a file into 
memory, verifying the CRC (Cyclic Redundancy Check). If the 
module is not already in the module directory, OS-9 adds it. 


If the program module is already in memory, the load process 
still begins in the same way. But, when OS-9 attempts to add 
the module to the module directory and notices that the module 
is already there, it merely increments the known module’s link 
count (the number of processes using the module). 


When OS-9 loads multiple modules in a single file, it associates 
them logically in the memory management system. You cannot 
deallocate any of the group modules until all modules have zero 
link counts. Similarly, linking to one module within a group 
causes all other modules in the group to be mapped into the pro- 
cess’s address space. 


Deleting Modules From Memory 


UNLINK is the opposite of LOAD. It decreases a program mod- 
ule’s link count by one. When the count becomes zero (presum- 
ing that the module is no longer used by any process), OS-9 
deletes the module, deallocates its memory, and removes its 
name from the module directory. 


Warning: Never use the UNLINK command on a program 
or a module not previously installed using LOAD. Unlink- 
ing a module you did not LOAD (or LINK) might perma- 
nently delete it when the program terminates. The shell 
automatically unlinks programs loaded by fork. 
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Suppose you plan to use the COPY command ten times in a row. 
Normally, the shell must load COPY each time you enter the 
command. But if you load the COPY module into memory and 
then enter your string of commands, you don’t have to wait for 
the system to load and unload COPY repeatedly. When you fin- 
ish using COPY, use UNLINK to unlock the module from mem- 
ory. The sequence looks like this: 


load copy (ENTER | 

copy filel fitetle LENE 
eopy Tilee Tiled. ENTER 
copy file3 filesa (EN 
copy Tiler: Ti leda 
copy Tiles Titlesa 
copy fileG file6Ga (ENTER 
copy Tider F1167a- EN 
copy file8 file8a [ENTE 
copy Tiled Tile9a | ENTER 
copy file1@ file1@a [ENTER] 
unlink copy 


It is important to use UNLINK when you no longer need the 
program. Otherwise, the program continues to occupy memory 
that might be used for other purposes. 
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Warning: Be careful not to unlink modules that are in use, 
because OS-9 deallocates the memory used by the module 
and destroys its contents. All programs using the unlinked 
module crash. 


Loading Multiple Programs 


Because all OS-9 program modules are position-independent, you 
can have more than one program in memory at the same time. 
Since position-independent code (PIC) programs don’t have to be 
loaded into specific, predetermined memory addresses to work 
correctly, you can load them at different memory addresses at 
different times. 


PIC programs require special types of machine language 
instructions that few computers have. The ability of the 6809 
microprocessor to use PIC programs is a powerful feature and 
one of the greatest aids toward multiprogramming. You can load 


any number of program modules until available system memory 
is full. 
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OS-9 automatically loads each program module at non-overlap- 
ping addresses. (Most operating systems write over the previous 
program’s memory when loading a new program.) OS-9’s tech- 
nique means that you do not need to be concerned with absolute 
memory addresses. 
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Useful System Information 
and Functions 


The OS-9 system must load many parts of the operating system 
during startup and system operation. Therefore, on a floppy disk 
system, you must keep the system diskette in Drive /DO. 


Two files used during the system startup operation, OS9Boot 
and Startup, must remain in the system diskette’s ROOT direc- 
tory. Other files on the system diskette are organized into two 
directories: CMDS (commands) and SYS (other system files). You 
can also create other files and directories on the system diskette. 
OS-9 always creates the initial data directory, or ROOT direc- 
tory, when you format a diskette. 


File Managers, Device Drivers, and 
Descriptors 

The bootstrap (instructions that initialize OS-9) loads a file 
called OS9Boot into RAM memory at startup. This file contains 
file managers, device drivers and descriptors, and any other mod- 


ules that permanently reside in memory. For instance, the 
OS9Boot file might contain these modules: 


OS9p2 OS-9 Kernel 


INIT System Initialization Table 

IOMan OS-9 input/output manager 

RBF Random block (disk) file manager 

SCF Sequential character (terminal) file manager 
PipeMan Pipeline file manager 

Piper Pipeline driver 

Pipe Pipeline device descriptor 


CC3IO Keyboard/video graphics device driver 
VDGINT 32x16 screen subroutines 

GRFINT  Windowing subroutines 

PRINTER Printer device driver 

SIO RS-232 serial port device driver 
CC3Disk Disk driver 

DO, D1 Disk device descriptor 

TERM Terminal device descriptor 


T1 RS-232 serial port device descriptor 
P Printer (serial) device descriptor 
Pl Printer (serial) device descriptor 
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Clock Real-time clock module 

CC3GO System startup process 

W-W7 Window device descriptors W, W1, W2, W3, 
W4, W5, W6, W7 


OS-9 stores the modules loaded during the system startup with 
a minimum of fragmentation. To include additional modules, cre- 
ate new bootstrap files using the OS9GEN command or the 
CONFIG program supplied with OS-9. You cannot unlink a mod- 
ule loaded as part of the bootstrap. 


After booting, when the system switches the boot block into its 
own address space, any non-system files included in the boot- 
strap decrease the memory available in the system mode. It is 
best to place optional modules in a separate file and load them 
as part of the system startup procedure. One example is the 
shell. Never include the shell as part of a system boot file in 
OS-9 Level Two systems. 


The Sys Directory 

The OS-9 SYS directory contains a number of important files: 
@ Errmsg is the error message file. 
@ Helpmsg contains syntax and usage information. 


@ Stdfonts contains the standard software fonts for use on 
graphic windows. 


@ Stdpats__2, Stdpats__4, and Stdpats__16 contain screen 
background and fill patterns for 2, 4, and 16 color graph- 
ics screens, respectively. 


e Stdptrs contains graphic pointer images for use with a 
mouse. 


These files, and the SYS directory itself, are not required to boot 
OS-9, but you do need them if you plan to use the ERROR or 
HELP commands, or if you intend to use text, or mouse pointers 
on graphic windows. You can also add other system-wide files of 
a similar nature. 
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The Startup File 


The Startup file (/DO/startup) is a shell procedure file that OS-9 
automatically processes as part of the system boot. You can 
include any legal shell command line in the Startup file. Many 
people include SETIME to start the system clock. If this file is 
not present, the system starts correctly, but the system time is 
not accurate. 


The CMDS Directory 


The directory /DO/CMDS is the system-wide command directory 
normally shared by all users as their working execution direc- 
tory. The shell resides in the CMDS directory. The system start- 
up process CC3go makes CMDS the initial execution directory. 
You can add your own programs to the CMDS directory and have 
them execute in the same manner as the original system 
commands. 


Making New System Diskettes 


Getting Started With OS-9 told you how to create new system 
diskettes using the CONFIG utility. There are other ways to cre- 
ate system diskettes and either add or subtract capabilities. The 
following information provides guidelines on how to do this. For 
more detailed instructions see the descriptions of the CONFIG, 
OS9GEN, and COBBLER commands in this manual. 


Before starting any of the following procedures, you need a 
blank, formatted diskette on which to place your system files. 
Then, choose one of the following methods to update your 
system: 


@ Use the OS9GEN command to add modules to the exist- 
ing OS9Boot file. 


@ Use CONFIG to select the modules you want to include 
in the OS9Boot file. 
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If you choose to use CONFIG, the utility creates a complete sys- 
tem during the process. If you use OS9GEN, follow these steps: 


1. Create the OS9Boot file using OS9GEN. 
2. Create or copy the Startup file. 


3. Copy the CMDS and SYS directories and the files they 
contain. 


You can perform these steps manually or do them automatically 
by using one of these methods: 


@ Creating and using a shell procedure file 


@ Using a shell procedure file generated by DSAVE 


Technical Information for the RS-232 Port 


You can operate the RS-232 port or the printer at all standard 
baud rates from 110 baud to 19200 baud. (The default rate is 
9600 baud for /t2, and 600 baud for /p.) The default format used 
is 8 data bits, no parity, and 1 stop bit. 


Use the XMODE command to set the port’s baud rate, parity, 
word length, stop bits, end-of-line delay, auto line feed, and so 
forth. To examine the printer’s current settings, type: 


xmode /p [ENTER 


Then, if you want to make changes, use XMODE with informa- 
tion from the following chart. Select the parameter you want 
from the left column of each chart, and then select the corre- 
sponding number from the “Value to Use” column and write it 
down. After you select the proper value from each chart, add 
them together to obtain a final value for XMODE. All values 
must be hexadecimal. 
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Stop Bits Word Length Baud Rate 
Number of Value Word Value Bits Per Value 
Stop Bits to Use Length |to Use Second to Use 
1 Stop Bit 0 20 110 BPS 

300 BPS 


600 BPS 
1200 BPS 
2400 BPS 
4800 BPS 
9600 BPS 

19200 BPS 


2 Stop Bits 


“IM Or GDF © 


For instance, to set the printer parameters to one stop bit, a 
word length of seven bits, and a baud rate of 600, select 0 from 
the Stop Bits chart, 20 from the Word Length chart, and 2 from 
the Baud Rate chart. Add the values together: 


O20 + 2. = 22 


The command to set the printer port for this configuration is: 


xmode /p baud=22 [ENTER] 


When you use XMODE to set baud, parity, and stop bit values, 
you are actually setting the bits of a special byte to certain val- 
ues. OS-9 uses these values to determine how to handle subse- 
quent input/output operations. A bit is a binary digit and can be 
either 1 or 0. A byte consists of eight bits and can represent a 
value between 0 and 255. 


The following chart shows the bits that control baud rate, word 
length, and stop bits for input/output operations on a specified 
device. 
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Bit 7 65 4 3 2 1 0 


ae Baud rate 
Reserved 
Word length 
Stop bits 
If the stop bit value = 0, stop bits = 1 
If the stop bit value = 1, stop bits = 2 


If the word length value = 00, word length = 8 bits 
If the word length value = 01, word length = 7 bits 


If the baud rate value = 0, baud rate = 110 
If the baud rate value = 1, baud rate = 300 
If the baud rate value = 2, baud rate = 600 
If the baud rate value = 3, baud rate = 1200 
If the baud rate value = 4, baud rate = 2400 
If the baud rate value = 5, baud rate = 4800 
If the baud rate value = 6, baud rate = 9600 
If the baud rate value = 7, baud rate = 19200 
(/t2 ACIAPAK only) 
If the baud rate value = 7, baud rate = 32000 


(/t1 SIO only) 


Use XMODE TYPE=value to set parity, MDM (modem) kill, and 
the not ready delay. Value is a hexadecimal value you calculate 
from the following chart: 


Parity MDM Kill Not Ready Delay 


Type of Value Kill Value 
Parity to Use Switch |to Use 


On 10 
Off 0 


0 seconds 
1 second 
2 seconds 


3 seconds 


m+ + ¢ ¢€ WONWrHO 


15 seconds 
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Select a value from each chart, and add them together to get a 
final TYPE value. For instance, to select even parity, MDM kill 

off, and a not ready delay of 10 seconds, select these values and 
add them: 


60+0+A=6A 
To set the new values, type: 


xmode /p type=6a (ENTER ] 


The following chart shows the bits that control parity, the 
modem kill switch, and the not ready delay. 


Bit T | Lo. 


ie ready delay 
(printer only) 
MDM kill switch (ACIAPAK/ 
MODPAK devices) 
oo, 


Parity 


If the parity value is 000, then parity = none 
If the parity value is 101, then parity = MARK, no check 
If the parity value is 111, then parity = SPACE, no check 


If the MDM kill switch value is 0, then DCD loss = no kill 
If the MDM kill switch value is 1, then DCD loss = kill 


The value of the not ready delay bits equals the number of 
seconds delay. 


For more information on setting other parameters, such as the 
end-of-line delay (null count), see the XMODE command refer- 
ence in Chapter 6. 
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System Command Descriptions 


This chapter contains alphabetical descriptions of the commands 
supplied with OS-9. Ordinarily, you call the commands from the 
shell, but you can also call them from most other programs in 
the OS-9 family—including BASICO9 and the Macro Text Editor. 


Warning: Do not attempt to use OS-9 Level One commands 
with the OS-9 Level Two system or to use Level Two com- 
mands with the Level One system. 


Organization of Entries 
Each command entry includes: 
@ The name of the command 


e A syntax line, which shows you the format and spelling 
to use when you type the command 


@ A brief definition of what the command does 


e Information about any options available with the 
command 


@ Notes about the command and how to use it 


@ One or more examples of command use 


Command Syntax Notations 


OS-9 requires that you enter the various parts of a command in 
the correct order and in the correct format. An example of the 
proper syntax follows the command name. 


The syntax line always begins with the name of the command. 
Occasionally, that’s all you need (except for pressing [ENTER]). But 
other commands either require, or can accept, parameters (vari- 
ables that give instructions to OS-9). 


Some syntaxes include variables (shown in italics) that you 
replace with specific parameters. For instance, the BUILD com- 
mand syntax is: 


build filename | ENTER 
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BUILD is the command name. You type it exactly as shown. 
However, filename is a variable. Replace it with the actual name 
you want to give to the file you are creating. If you want to cre- 
ate a file named Myfile, type: WwW 


buiid myfile ENTER 
Pressing (ENTER] executes the command. 
Common variables are: 


arglist arglist (argument list) is similar to paramlist, 
but it includes command names as well as 
command parameters. 


deuname device name (/P, /TERM, /M1) 


commandname command name 


dirname directory name 
filename file name 
hex a hexadecimal number 
hh/mm/ss hour/minutes/seconds ed 
modname name of a memory module | 
n a decimal number | 
number a numeric value 
opts options 
paramlist a list of parameters 
pathlist a complete path to a directory or file 
permission file permission abbreviations 
proclD process ID number | 
text a string of characters | 
tickcount a numeric value representing system clock 

ticks J 
value a numeric value | 
yy/mm/dd year/month/day 


6-2 


System Command Descriptions / 6 


[ ] Brackets indicate that the material within them is optional 
and not necessary for the execution of the command. 


.. An ellipsis indicates that you can repeat the material imme- 
diately preceding the ellipsis. For instance, [filename]|...] means 
that you can specify more than one filename to the command. 
Following is the syntax for the DISPLAY command: 


display hex fi teal 


This means you can include more than one hex number with 
DISPLAY, such as: 


display 54 48 49 53 20 49 53 20 41 20 53 45 43 
52 45 54 20 4D 45 53 53 41 47 45 [ENTER] 


Command syntaxes do not include the shell’s built-in options (for 
instance I/O redirection) because the shell filters out its options 
before it passes the command line to the program being called. 


Command Summary 
This section describes the format and use of OS-9 commands. 


The following list is a summary of these commands: 


ATR yi distene Changes a file’s attributes 

BACKUP..... Makes a copy of a diskette 

BUILD....... Builds a text file 

CHD eke Changes the working data directory 

CH pieces Changes the working execution directory 

COP crcc2 gee Compares files 

COBBLER ... Makes an OS9Boot file 

CONFIG ..... Creates a system diskette to your specifications 

COPY age cons Copies data 

DATE ........ Displays the system date and (optionally) the 
time 

DCHECK .... Checks a disk file structure 

DEINIZ ...... Deinitializes a device previously initialized with 
INIZ 

| 1) Cnr ere Deletes a file or files 

DELDIR ..... Deletes a directory’s files, then deletes the 
directory 

DUR. ic hiaceuss Displays the names of all files in a directory 

DISPLAY ..... Displays the characters represented by hexadeci- 
mal values 

DSAVE....... Generates a procedure file to copy files 
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ECHO ....... Echoes text to the screen 

MODELS 2.48244 Calls the OS-9 Macro Text Editor 

ERROR ...... Displays a description of the last error code 

+) See eee Causes the shell process to execute another 
process 

FORMAT .... Prepares a disk for data storage 

FREE........ Displays the amount of free space on a disk 

|g OH OP gee rr Displays the syntax and use of commands 

IDENT ices Displays OS-9 module identification 

LINED ken vanes Initializes and attaches devices 

WOE se Goce Terminates a process 

IGN: ban ewone Links a module into memory 

LIS cance nees Lists the contents of disk data files 

LOAD........ Loads a module into memory 

MAKDIR .... Creates a directory 

MD oe eee Displays the names of the modules in memory 

MERGE...... Copies and combines files 

MFREE...... Displays a list of free RAM 


MODPATCH.. Makes changes to a module in memory 
MONTYPE ... Establishes the type of monitor in use 
OS9GEN ..... Builds and links a bootstrap file 


PROCS ...... Displays the names of the current processes 

PWD yccrekes Displays the name of the current data directory 

PAs coneieas Displays the name of the current execution 
directory 

RENAME .... Changes the name of a file or directory 

SETIME ..... Activates and sets the system clock 

SETPR....... Sets a process’s priority 

SHELL ...... Creates a child shell to process one or more 
commands 

TMODE ...... Changes the terminal’s operating mode 


TUNEPORT Adjusts the loop delay for the baud rate of /P or 
/T1 devices 

UNLINK ..... Unlinks memory modules 

WCREATE ... Creates a window 

XMODE ...... Displays or changes a device’s initialization 
parameters 
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ATTR 


Syntax: attr filename [permission] 


Function: Lets you examine or change a file’s security 


permissions. 
Parameters: 
filename The name of the file you want to examine or 
change. 
permission One or more of the following attribute options. 
Options: 


The file permission abbreviations you can use are: 


-d Changes a file directory file to not a non-directory 
file. 

S Specifies that the file is not single-user and can serve 
only one user at a time. 

r Specifies that only the owner can read the file. 

Ww Specifies that only the owner can write to (change) 
the file. 

e Specifies that only the owner can execute the file. 

pr Specifies that the public (anyone) can read the file. 


pw Specifies that the public (anyone) can write to the file. 
pe Specifies that the public (anyone) can execute the file. 


-a Tells ATTR not to display the attributes. Use this 
option when you wish to change attributes without 
displaying them. 
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Notes: 


e To use ATTR, type the command name followed by the 
name of the file you want to change. Next, type a list of the , 
permissions to turn on or off. Turn a permission on by typ- 
ing its abbreviation or off by typing its abbreviation pre- | 
ceded by a minus sign. ATTR has no effect on permissions | 
you do not name. 
| 
| 


e If you do not specify any permissions, ATTR displays the 
file’s current attributes. 


@ You cannot change the attributes of a file you don’t own. 
User 0 can change the attributes of any file in the system. 


@ Use ATTR to change a directory into a file after deleting 
all the directory’s files. You cannot change a file to a direc- | 
tory with ATTR. (See MAKDIR.) | 


Examples: 


@ To remove public read and write permission from a file 
named Myfile, type: 


attr myfile -pr -pw (ENTER] 


@ To give read, write, and execute permission to everyone for 
the file Myfile, type: 


attr myfile r we pr pw pe (ENTER] 


@ To display the current permissions of a file named Datalog, 
type: 


attr datalog 
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Syntax: backup [opts][devname!][|devname?2| 


Function: Copies all data from one disk to another. 


Parameters: 


devnamel 
devname2 
opts 


Options: 


ov 


#nKk 


Notes: 


The drive containing the disk files you want to 
back up. 


The drive containing the disk to which you 
want to transfer the files. 


One or more of the following options. 


Cancels the backup if a read error occurs. 


Lets you backup a diskette using only one 
drive. 


Tells BACKUP not to verify the data written 
to the destination diskette. 


Increases to n the amount of memory that 
BACKUP can use. Increasing the amount of 
memory assigned to BACKUP speeds the pro- 
cedure. 7 can be either in pages of 256 bytes 
or in kilobytes (1024 bytes). Include K to indi- 
cate kilobytes. 


@ BACKUP performs a sector by sector copy, ignoring file 
structures. In all cases, the devices specified must have the 


same format 


(size, density, and so forth) and the destina- 


tion disk must not have defective sectors. 
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e If you omit both device names, the system assumes you are 


copying from /DO to /D1. If you omit only the second device 
name, OS-9 performs a single-drive backup on the specified 
drive. 


The following demonstrates a complete backup of /DO to 
/D1. In the example, the diskette in Drive /D1 is a format- 
ted diskette with the name MYDISK. Scratched, which 
appears in one of the following messages, means erased. 
You type: 


backup 
The screen display and your input are: 


Ready to backup from /d@ to /d1 ?: 
MYDISK 
is being scratched 
OK? : (Y) 
Sectors copied: $8276 
Verify pass 
Sectors verified: $9276 


Following is an example of a single-drive back up. BACKUP 
reads a portion of the source diskette (the diskette you are 
copying) into memory. It then prompts you to remove the 
source diskette and put the destination diskette (the 
diskette receiving the copy) into the drive. 


After BACKUP writes to the destination diskette, remove 
the destination diskette and put the source diskette back 
into the drive. Continue swapping as prompted until 
BACKUP copies the entire diskette. 


Giving BACKUP as much memory as possible means you 
have to make fewer diskette exchanges. If enough free mem- 
ory is available, you can assign up to 56 kilobytes for the 
backup operation. An Error 207 means that your computer 
does not have the specified amount of memory free. To 
assign 32 kilobytes to backup, type: 


backup /d®@ #32k 
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The screen display and your responses are as follows: 


Ready to backup from /d@ to d@ ?: 


Ready Destination, hit a key: 
MYDISK 


is being scratched 

OK? : 

Ready Source, hit a key: 
Ready Destination, hit a key: 
Ready Source, hit a key: 
Ready Destination, hit a key: 


| 
V 


Ready Destination, hit a key: 
Sectors copied: $8276 


Verify pass 
Sectors verified: $@276 


In this procedure, the dollar symbol ($) indicates hexadeci- 
mal numbers. BACKUP copied 276 hexadecimal (or 630 
decimal) sectors. 


Examples: 


@ To back up the diskette in Drive /D2 to the diskette in 
Drive /D8, type: 


backup /d2 /d3 


@ To back up from Drive /DO to Drive /D1, without verifica- 
tion, type: 


backup -v | ENTER 
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BUILD 


Syntax: build filename 


Function: Builds a text file by copying input from the stan- 
dard input device (the keyboard) into the file specified by 
filename. 


Parameters: 


filename The name of the file you are creating. 


Notes: 


e BUILD creates a file, naming it filename. It then displays a 
question mark (?) and waits for you to type a line. When 
you type a line and press [ENTER], BUILD writes the line to 
the disk. 


@ When you finish entering the lines for the new file, press 
[ENTER], without any preceding text, to close the file and ter- 
minate the operation. 


@ The following example demonstrates how to build a text file 
named Newfile: 


build newfile 


? THE POWERS OF THE OS-9 [ENTER] 

? OPERATING SYSTEM ARE TRULY 
? FANTASTIC. 

? 


@ To view the newly created file, type: 


list newfile|ENTER 
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The screen displays: 


THE -POWERS DF THE. OS=9 
OPERATING SYSTEM ARE TRULY 
FANTASTIC. 


Examples: 


@ To create a new file called Small_file and put into it what- 
ever you type at the keyboard, type: 


Build small_file 
@ To direct whatever you type to the printer, type: 


build /p (ENTER] 


@ You can use BUILD to transfer, or redirect, data from one 
file to another. Instead of the keyboard, this example uses a 
file named Mytext file for the input device. The output 
device is Terminal] 1. 


build <mytext /t1 


OS-9 Commands Reference 


CHD 
CHX » 


Syntax: chd pathlist 
chx pathlist 


Function: CHD changes the current working (data) directory, 
and CHX changes the current execution directory. 


Parameters: 
pathlist Specifies the directory for the current working 
or execution directory. 
Notes: 
e CHD and CHX do not appear in the CMDS directory | 
because they are built into the shell. | 
Examples: 
@ To change the current working (data) directory to the PRO- 
GRAMS data directory located on the diskette in Drive 
/D1, type: 
chd /d1/programs 
@ To change the execution directory to the parent directory of 
the current execution directory, type: 
SHR es 
@ To change the execution directory to TEXT_PROGRAMS, 
a subdirectory of BINARY_FILES, type: WJ 


chx binary—files/text—programs 
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e To return the execution directory and the data directory 
back to the default directories, type: 


chx /d@/cmds; chd /d@ [ENTER] 
Or, if you are using a hard disk, type: 


chx /h@/cmds; chd /h@ [ENTER] 
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CMP 


Syntax: cmp filename! filename2 


Function: Opens two files and compares the binary values of 
corresponding data bytes in the files. If CMP encounters any 
differences in the file, it displays the file offset (address) and 
the values of the bytes from each file. 


Parameters: 


filenamel are the files to compare. 
filename2 


Notes: 


@ The comparison ends when CMP encounters an end-of-file 
marker in either file. CMP then displays a summary of the 
number of bytes compared and the number of differences 
found. 


Examples: 


@ To compare two files named Red and Blue, type: 


cmp red blue 
Following is a sample screen display: 


Differences 


byte #1 #2 
90000013 00 4&1 
g9000022 BO BI 
09000028 9B AB 
0000002B 3B 36 
go00002C 6D 65 


Bytes compared: 90000@2D 
Bytes different: 80000005 


6-14 


System Command Descriptions / 6 


@ To compare two files that are identical, such as Redl and 
Red2, type: 


cmp red1 red2 
The screen display might be: 


Differences 
None 


Bytes compared: 902080082eD 
Bytes different: @080000090 
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COBBLER 


Syntax: cobbler devname 


Function: Creates the OS9Boot file required on any OS-9 boot 


diskette. 
Parameters: 
devname The disk drive containing the diskette on 
which you want to create a new OS9Boot file. 
Notes: 


@ COBBLER creates the new OS9Boot file with the same 
modules loaded during the most recent bootstrap. (To add 
modules to the bootstrap file, use OS9GEN.) COBBLER 
also writes the OS-9 kernel on Track 34 and excludes these 
sectors from the diskette allocation map. If any files are 
present on these sectors, COBBLER displays an error 
message. 


@ The new boot file must be contiguous on the diskette. For 
this reason, you should use COBBLER only with a newly 
formatted diskette. If you use COBBLER on a diskette that 
does not have a storage block large enough to hold the boot 
file, COBBLER destroys the old boot file, and OS-9 cannot 
boot from that diskette. 


e To change device attributes permanently, use XMODE 
before using COBBLER. 


Examples: 


@ To save the attributes of the current device on the system 
diskette, type: 


cobbler /d@ 
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If you use COBBLER on a diskette that is not newly format- 
ted, the screen displays: 


WARNING - FILECS) OR KERNEL 
PRESENT ON. TRACK 34 = THIS 
TRACK NOT REWRITTEN 
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CONFIG 


Syntax: config 


Function: Lets you create a system diskette that includes only 
the device drivers and commands you select. CONFIG auto- 
matically adjusts its screen display for either 32- or 80-column 
display. 


Notes: 
@ When executed, CONFIG displays menus of all I/O options 


and system commands. You select only those options and 
commands you want to include on a new system diskette. 


Creating such a system diskette lets you make the most 
efficient use of computer memory and system diskette 
storage. 


The CONFIG utility is on the BASICO9/CONFIG diskette. 
Copy this diskette, using the OS-9 BACKUP command. 
Make the copy your working diskette. Keep the original in 
a safe place to use for future backups. After you boot your 
system, you can put the working copy of the BASIC09/ 
CONFIG diskette in drive /d0. Then, type these commands: 


chx /d®@/cmds; chd /d@/modules [ENTER] 


CONFIG does not require initial parameters. You establish 
parameters during the operation of the command. Be sure 
the execution directory is /DO0/CMDS before executing 
CONFIG. 


You could save time by using BACKUP to create a system 
disk, using CONFIG to create a new boot file, and then 
deleting unwanted commands. However, this process causes 
fragmentation of diskette space and results in slower disk 
access. CONFIG causes no fragmentation. 


6-18 


System Command Descriptions / 6 


@ The MODULES directory of the BASICO9/CONFIG diskette 

contains all the device drivers and device descriptors sup- 

cf ported by OS-9. The filename extension describes the type 
of file, as noted in the following table: 


Extension Module Type 


.dd Device Descriptor module 
.dr Device Driver module 
lo Input/Output subroutine module 
-hp Help file 
dw Window Device Descriptor module 
dt Terminal Device Descriptor module 
.mn File Manager module 

Examples: 


The following steps take you through the complete CONFIG 
process: 


1. With the BOOT/CONFIG diskette in the current drive, 
cy type: 


config ENTER 


2. CONFIG asks whether you want to use one or two disk 
drives. Press (1) for single- or (2) for two-drive operation. 


If you specify one drive, continue with Step 3. 
If you specify two drives, a display asks you to: 
ENTER NAME OF SOURCE DISK: 
Type /d@ 
A display now asks you to: 
ENTER NAME OF DEST. DISK: 


Type /d1 


am 3. After a pause to build a descriptor list, the program dis- 
plays a list of the various devices from the MODULES 
directory. Use and to move to a device. To include 
the device on the system diskette, press once. CONFIG 
displays an X by the selected device. To exclude a selected 
device, press {S$} again to erase the X. 
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A special help command provides information about each 
device. To display information about the current device (the 
device indicated by the arrow (-+)), press [(H). 


The list of devices might require more than one screen. Use 
to move ahead page by page and to move back. 


The devices you can select and their descriptions are listed 
in Chapter 2 under the section “Device Names.” 


You must select a “DO” device as your first disk drive. 
Select from the list of D devices for other floppy disk drives. 
Select P to use a printer with OS-9, T1 to use a terminal, 
M1 to use a modem, and so on. 


. After selecting the devices you desire, press (D}. The screen 


displays, ARE YOU SURE CY/N) ? If you are satisfied with 
your selections, press (Y}. If you want to make changes, 


press (N]. 


. To use your computer keyboard and video display, you must 


select either TERM_VDG or TERM_WIN. You use 
TERM_VDG for a 32-column display. For a TERM window 
that enables you to select character displays up to 80-col- 
umns, select TERM_WIN. 


. CONFIG builds a boot list from the selected devices and 


their associated drivers and managers in the MODULES 
directory of the current drive. It next displays two clock 
options: 


1 - 6BHZ CAMERICAN POWER) 
2 - S0HZ CEUROPEAN POWER) 


. If you live in the United States, Canada, or any other coun- 


try with 60hz electrical power, press {1}. If you live in a 
country with 50hz power, press (2). 


If you have a single disk drive, a screen prompt asks you to 
swap diskettes and press (C). When asked for the SOURCE 
diskette, insert the BASICO9/CONFIG diskette. When 
asked for the DESTINATION diskette, insert the diskette 
that is to be your new OS-9 system diskette. 


If you have more than one drive, a screen prompt asks you 
to insert a blank formatted diskette (the DESTINATION 
diskette) in the destination drive. The rest of the boot file 
creation is automatic. 
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8. After creating the boot file, CONFIG displays a menu of the 
commands you can include on your system diskette. You 
have the following choices: 


[N]lo Commands, Stop Now — Do not add any commands 

[Flull Command Set — Add all OS-9 commands 
from the current CMDS 
directory 

[I]ndividually Select — Select commands one by 
one 

[H] Receive Help — Get help on the command 
set 


Press (N] if you want to transfer a new boot file to a 
diskette on which you have previously copied the OS-9 sys- 
tem. If you have only one disk drive, this procedure is 
quicker than using the CONFIG utility to complete the 
entire system transfer, because it requires fewer disk 
swaps. 


Press to make an exact copy of the CMDS directory on 
your source diskette with a new boot file. 


Press {1} to individually select commands to copy on the 
new diskette. The [1] option displays a menu similar to the 
device selection screen. Press to select or exclude com- 
mands, and use the arrow keys to move among the com- 
mands in the menu. CONFIG selects files marked with an 
X for inclusion on the new system diskette. If a command 
does not have an X beside it, CONFIG excludes it from the 
new system diskette. 


9. If you have a multi-drive system, a prompt appears asking 
you to insert your OS-9 system diskette in the destination 
drive. Press the space bar. The process finishes the CON- 
FIG operation, and returns to OS-9. 


If you have a single-drive system, you swap diskettes dur- 
ing the final process. This time, the SOURCE diskette is 
the OS-9 System diskette. The DESTINATION diskette is 
the system diskette you are creating. The number of swaps 
depends on the number of options you select. 


Note: When using CONFIG you do not have to use 
your system diskette as the source diskette to install 
the commands. The program can use any diskette 
that contains a CMDS directory. 
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COPY 


Syntax: copy pathlistl pathlist2 [opts] 


Function: Copies data from one file or device to another file or 


device. 


Parameters: 
pathlist1 


pathlist2 


Options: 


=5 


#n[K] 
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The name of the existing file or device from 
which you want to copy. 


The name of the device or file to receive the 
copy. If you are copying data to a file, the file 
must not already exist. 


Causes COPY to perform a single-drive copy 
operation. pathlist2 must be a full pathlist if 
you use -s. In a single-drive procedure, COPY 
reads a portion of the source disk into memory 
and then asks you to exchange the source and 
the destination diskette and press (C}. COPY 
might ask you to exchange diskettes several 
times before it completes duplicating the 
entire file. 


Allows the use of more memory for the COPY 
procedure. If you specify K, n represents the 
amount of memory you want to use, in units of 
1024 bytes. If you do not specify K, n repre- 
sents the number of 256-byte memory pages. 
Using this option can increase speed and 
reduce the number of diskette swaps required 
for single-drive copies. 


cy 
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Notes: 


@ If pathlist2 is a disk file, COPY automatically creates it. Data 


can be of any type, and COPY does not modify the file in any 
way. 


COPY does not add important codes (for example, line feeds). 
Use LIST instead of COPY when sending a text file to a ter- 
minal or printer. 


Following is an example of the screen display and your 
responses for COPY using a single drive: 


copy /d@/cat /d@/animals/cat -s #32k 
Ready DESTINATION, hit C to continue: 
Ready SOURCE, hit C to continue: 

Ready DESTINATION, hit C to continue: 


v 


v 


This example assigns 32 kilobytes of memory for COPY to 
use. If enough free memory is available, you can specify up 
to 56 kilobytes. Copy continues asking you to swap the 
source and destination diskettes until the transfer is 
complete. 


Examples: 


@ To copy Filel to File2 using 15K of memory, type: 


copy filet file2 #15k (ENTER] 


@ To copy the News file on the diskette in Drive /D1 to a new 


file named Messages on the diskette in Drive /DO, type: 


copy /d1/joe/news /d@/peter/messages 
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DATE 


W 
Syntax: date [t] 
Function: Displays the current date. 
Options: 
t Causes the time to appear with the date. 
Notes: 
@ Following is an example of how to use SETIME to set a new 
date and time for the system and how to use DATE to 
check system date and time: 
setime | 
A possible screen display and your responses follows: | 
yy/mm/dd hh.mm.ss Y 
Time? 86/08/22 14.19.00 (ENTER } 
date | 
| 
August 22, 1986 
date t 
August 22, 1986 14.20.20 
Examples: 
@ To display the system date and time, type: 
date t 
@ To direct the DATE command’s output to the printer, type: 


date t >/p 
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DCHECK 


Syntax: dcheck [-opts] devname 


Function: Checks a disk’s file structure. 


Parameters: 
devname 
opts 

Options: 


-S 


b 


-p 
-w = pathlist 
-m 


-O 


Notes: 


The disk drive to check. 


One or more of the following options. 


Counts the number of directories and files and 
displays the results. This option causes 
DCHECK to check only the file descriptors for 
accuracy. 


Suppresses listing of unused clusters (clusters 
allocated but not in the file structure). 


Prints pathlists for questionable clusters. 
Specifies a path to a directory for work files. 
Saves allocation map work files. 


Prints DCHECK’s valid options. 


@ Sometimes the system allocates sectors on a disk that are 
not actually associated with a file or with the disk’s free 
space. This situation can happen if you remove a disk from 
a drive while files are open. You can use DCHECK to 
detect this condition, as well as check the general integrity 
of directory/file links. 
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After verifying and printing some vital file structure 
parameters, DCHECK follows pointers down the disk’s file 
system tree to all directories and files on the disk. As it 
does so, it verifies the integrity of the file descriptor sec- 
tors, reports any discrepancies in the directory/file links, 
and builds a sector allocation map from the segment list 
associated with each file. If any file descriptor sectors 
(FDS) describe a segment with a cluster not within the file 
structure of the disk, DCHECK displays a message like 
this: 


*** Bad FD segment ($xxxxxx-$yyyyyy) for file: 
Cpathlist) 


This message indicates that a segment starting at sector 
xxxxxx and ending at sector yyyyyy is not on the disk. If 
any of the file descriptor sectors are bad, the entire FD 
might be defective. DCHECK does not update the alloca- 
tion map for corrupt FDS. 


While building the allocation map, DCHECK also ensures 
that each disk cluster appears once and only once in the file 
structure. If it discovers duplication, DCHECK displays a 
message like this: 


Cluster $xxxxxx was previously allocated 


This message indicates that DCHECK has found cluster 
xxxxxx more than once in the file structure. DCHECK 
reprints the message each time a cluster appears in more 
than one file. 


Then, DCHECK compares the newly created allocation map 
with the allocation map stored on the disk and reports any 
differences with messages like these: 


Cluster $xxxxxx in allocation map but not in file 
structure 


Cluster $xxxxxx in file structure but not in 
allocation map 


The first message indicates that sector number xxxxxx 
(hexadecimal) is not part of the file system, but the disk’s 
allocation map has assigned it. FORMAT might exclude 
some sectors from the allocation map because they are 
defective. 
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The second message indicates that the cluster starting at 
sector xxxxxx is part of the file structure, but the disk’s 
allocation map has not assigned it. Later operations might 
allocate this cluster, overwriting the contents of the cluster 
with data from the newly allocated file. (Clusters that 
DCHECK previously allocated can have this problem.) 


e DCHECK builds its disk allocation map in a file called 
pathlist/DCHECKpp0, where pathlist is specified by the -w 
option and pp is the process number in hexadecimal. Each 
bit in this bitmap file corresponds to a cluster of sectors on 
the disk. If you use the -p option, DCHECK creates a sec- 
ond bitmap file (pathlist2/DCHECKpp1) that has a bit set 
for each cluster DCHECK finds as “previously allocated” or 
“in file structure but not in allocation map.” DCHECK 
then makes another pass through the directory structure to 
determine the pathlists for these questionable clusters. You 
can save the bitmap work files by specifying the -m option 
on the command line. 


@ For best results, DCHECK should have exclusive access to 
the disk being checked. Otherwise, the command might be 
fooled by a change in the disk allocation map while 
DCHECK is building a bitmap file. DCHECK cannot pro- 
cess disks with more than 39 levels of directories. 


@ -p causes DCHECK to make a second pass through the file 
structure and print pathlists for clusters that are not in the 
allocation map but are allocated or existing in a file 
structure. 


-w tells DCHECK where to place its allocation map work 
file(s). The specified pathlist must be a full pathlist for a 
directory. (DCHECK uses directory /DO if you do not spec- 
ify -w.) If you doubt the structure integrity of the diskette 
being checked, do not place the allocation map work files on 
that diskette. 


Examples: 


® The following two examples demonstrate DCHECK 
sessions: 


dcheck /d2 
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A sample screen display might be: 


Volume = “My system disk” on device /de 
$0209A bytes in allocation map 

1 Sector per cluster 

$000276 total sectors on media 

Sector $@00002 is start of Root directory 
FD 

$0010 sectors used for id, allocation map 
and Root directory 

Building allocation map work file... 
Checking allocation map file... 


‘My system disk’ file structure is intact 


‘ directory 
e files 


dcheck -mpw=/d2 /d@ [ENTER] 


A sample screen display might be: 
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Volume - “System diskette’ on device /dé 
$0046 bytes in allocation map 

1 Sector per cluster 

$80022A total sectors on media 

sector $900002 is start of Root directory 
FD 

$0819 sectors used for id, allocation map 
and Root directory 

Building allocation map work file... 

Cluster #00048 was previously allocated 

*** Bad FD segment €$111111-$23AGFO0) for 
Fite: /DOSTEXRT/ TUNnky. tile 

Checking allocation map file... 

Cluster $900038 in file structure but not 
in allocation map 

Cluster $@900903B in file structure but not 
in allocation map 

Cluster $08001B9 in allocation map but not 
in file structure 

Cluster $9001BB in allocation map but not 
in file structure 
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Pathlists for questionable clusters: 

Cluster $@90038 in path: /d@/0S9boot 
Cluster $88003B in path: /d@/0S9boot 
Cluster $800048 in path: /d@/O0S9boot 
Cluster $0000490 in path: /d@/test/ 
double.file 


1 previously allocated clusters found 

2 clusters in file structure but not in 
allocation map 

2 clusters in allocation map but not in 
file structure 

1 bad file descriptor sector 


‘System diskette’ file structure 1s not 
intact 

5 directories 

25 files 
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DEINIZ 


Syntax: deiniz devname [...] 


Function: Deinitializes and detaches a device. 


Parameter: 
devname The name of one or more devices you want to 
deinitialize. 
Notes: 


@ Use DEINIZ with INIZ. For example, you can use INIZ to 
initialize a window, then redirect information to the win- 
dow. View the information by pressing until it 
appears. When you no longer need the window, use DEINIZ 
to remove the window and return its memory to the 
system. 


® DEINIZ performs an OS-9 I$Detach call for all specified 
devices. 


Example: 


To deinitialize the /wl1 (Window 1) device after it has been ini- 
tialized, type: 


deiniz wi | ENTER 


oo 
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DEL 


Syntax: del [-x] filename [...] 


Function: Deletes the file(s) specified. 


Parameter: 
filename The name of the file to delete. Include as many 
filenames as you want. 
Option: 
-X Causes DEL to assume the file is in the cur- 
rent execution directory. 
Notes: 


e You can delete only files for which you have write 
permission. 


You can delete a directory in two ways: (1) Delete all the 
files in the directory, change it to a non-directory file using 
ATTR, then use DEL to remove the directory, or (2) Use the 
DELDIR command. 


@ The following example shows what appears on the screen 
when you display a directory, delete one of the directory’s 
files, then display the directory again: 


dir /d1 [ENTER | 


directory oT /d1 14.29.46 
myfile newfile 


del newfile (ENTER] 
dir /d1 


directory of fal 742.39 237 
myfile 
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Examples: 


@ To delete files named Text_program and Test_program, 
type: 


del text—program test_program 


® To delete a file on a drive other than the current working 
drive, use a complete pathlist, such as: 


del /d1/number_five 


® To delete a file named Cmds.subdir in the current execu- 
tion directory, type: 


del -x cmds.subdir 
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DELDIR 


Syntax: deldir dirname 


Function: Deletes all subdirectories and files in a directory; 
then, deletes the directory itself. 


Parameter: 
dirname The pathlist to the directory you want to 
delete. 
Notes: 


@ DELDIR is a convenient alternative to individually deleting 
all the files and subdirectories from a directory before 
deleting the directory itself. 


@® When DELDIR runs, it displays a prompt after the com- 
mand line: 


deldir oldfiles (ENTER) 
Deleting directory Ti le. 


List directory, délete directory, or “uit? 
Cl/d/q) 


Pressing causes a DIR E command to run so you can 
see the directory files before DELDIR removes them. 


Pressing (0D) starts the deletion process. 
Pressing (Q} cancels the command. 


e@ The directory to be deleted might include other directories, 
which in turn might include other directories, and so forth. 
In this case, DELDIR begins with the lower directories and 
works its way upward. 


You must have write permission to delete any files and 
directories in this substructure. If not, DELDIR terminates 
when it encounters the first file for which you don’t have 
write permission. 
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@® DELDIR automatically calls DIR and ATTR. Therefore, 
these files must reside in the current execution directory. 
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DIR 


Syntax: dir [opts][dirname or pathlist| 


Function: Displays a formatted list of filenames in a directory. 
The output format adjusts itself for 80- or 32-column displays. 


Parameters: 
dirname The name of the directory you want to view. 
pathlist The pathlist to the directory you want to view. 
opts Either or both of the following options. 
Options: 


If you don’t specify any parameters, DIR shows the current 
data directory. 


x Displays the current execution directory. 


a Displays the entire description for each file: 
size, address, owner, permissions, date and 
time of last modification. 


Examples: 


@ To display the current data directory, type: 
dir 
@ To display the current execution directory, type: 


dir x [ENTER 


@ To display the entire description of all files in the current 
execution directory, type: 


dir x e| ENTER 
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@ To display the parent of the current data directory, type: 
dir 2s 


@ To display a directory named NEWSTUFF, type: ia 
dir newstuff 
@ Following is a sample 80-column DIR display using the e 
option: 
dir e 
The screen might display: 
Directory of . 16:58:12 
Qwner Last modified Attributes Sector Bytecount Name 
oF BS/OST 28 1631 | sess wr 3A6C = OS9Boot 
@ 85/05/20 1345 d-ewrewr 48 640 ~=©CMDS 
8 85/05/20 1358 d-ewrewr 177 Ag §=6SYS 
B. Sh/e5/28 135i = ===pwr 192 E startup 
@ 85/05/20 1351 d-ewrewr 194 Ee “DCPS . J | 
@ Following is an 80-column DIR display using no options: 
dir 
The screen might display: | 
Directory of « 16:58:37 | 
OS9Boot CMDS SYS ____ startup | 
DEFS | 
WO 
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@ Following is a 32-column DIR display using the e option: 


a dir e [ENTER] 
Directory of  «. Te252504 
Modified on Owner Name 
Attr Sector Size 
85/05/28 1643 ar OS9Boot 
Bae ase wr 8 3AGC 
85/05/20 1345 Q CMDS 
d-ewrewr 48 6490 
85/05/20 13590 9 na oe 
d-ewrewr Lie 2 Ag 
85/05/28 1351 ) startup 
altace taf cs 132 E 
85/05/20 1351 Q DEFS 
d-ewrewr 194 E@ 


@ Following is a 32-column DIR display using no options: 


—_ dir CENTER} 


Directory of »s l6o252729 
OS9Boot CMDS SYS 
startup DEFS 
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DISPLAY 


Syntax: display hex [...] 


Function: Reads one or more hexadecimal numbers (you type | 
as parameters), converts them to ASCII characters, and | 
writes them to the standard output (normally the screen). | 


Parameters: 


hex A list of one or more hexadecimal numbers. 


Notes: 


@ Use DISPLAY to send special characters (such as cursor | 
and screen control codes) to terminals and other I/O | 


devices. Ww | 


@ Following is an example of a command and the resulting 
output. ABCDEF are ASCII characters corresponding to 
hex 41 42 43 44 45 46. 


display 41 42 43 44 45 46 (ENTER) 
ABCDEF 


Examples: 


@ To reroute a form feed (hex OC) to the printer, type: 


display @C >/p 
@ To ring the bell through the video speaker, type: 


display. 87 
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Syntax: dsave [opts][devname][dirname] > pathlist 


Function: Copies or backs up all files in one or more 


directories. 


Parameters: 


devname 


dirname 


pathlist 
opts 


Options: 


-sinteger 


The drive on which the source directory exists. 
If you do not specify deuname DSAVE assumes 
Drive /DO. 


The name of the destination directory. Use 
CHD to make the current directory the direc- 
tory to receive the copies. 


A command procedure file in which DSAVE 
stores its output. 


One or more of the following options. 


Makes the destination or target diskette a sys- 
tem diskette by copying the source diskette’s 
OS9Boot file, if present. 


Indents for directory levels. 


Tells DSAVE not to process directories below 
the current level. 


Tells DSAVE not to include MAKDIR com- 
mands in the procedure file it creates. 


Sets memory for the copy parameter to integer 
kilobytes. 


Verifies copies by forking to CMP after copying 
each file. 
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Notes: 


DSAVE does not directly affect the system. Instead, it gen- 
erates a procedure file that you execute later to do the 
work. 


When you run DSAVE, it creates a procedure file (a file of 
commands). You then execute the newly created file by typ- 
ing its pathlist. The procedure contains all the commands 
to create and change directories as needed in order to copy 
the specified directory. DSAVE copies the files in the cur- 
rent data directory. It also copies the current data direc- 
tory subdirectories, unless you specify the -| option. 


To use DSAVE, first change the data directory to the direc- 
tory you wish to copy. Execute DSAVE by specifying the 
drive from which to copy and then redirecting output to a 
file to receive the copy commands. Be sure to name a file 
that does not already exist. 


When DSAVE completes the procedure, use CHD to change 
to the data directory to receive the copied files. Then, exe- 
cute the procedure file. 


If DSAVE encounters a directory file, it automatically 
includes MAKDIR and CHD commands in the output 
before generating COPY commands for files in the subdirec- 
tory. The procedure file exactly replicates all levels of the 
file system from the current data directory downward. 


If the current data directory is the ROOT directory of the 
disk, DSAVE creates a procedure file that backs up the 
entire disk file by file. This is useful when you need to copy 
a number of files from either disks formatted differently or 
from floppy diskettes to a hard disk. 


Examples: 


@ In the following series of commands, CHD positions you in 
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Then, DSAVE makes the procedure file Makecopy. Using 
CHD /D1 causes the copy to go in the /D1 ROOT directory. 
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chd /d2 (ENTER) 

dsave /d2 >/d®/makecopy (ENTER | 
chd /d1 
/d®@/makecopy (ENTER ] 


@ The following command copies all files from /DO to /D1. It 
pipes the procedure file output of DSAVE into a shell for 
immediate execution. 


dsave /d®@ /d1 !_ shell [ENTER] 


@ The following command lets you view the output generated 
by a DSAVE command. It uses 48 kilobytes of memory and 
indents directories. Because output goes to the screen, this 
command does not create a procedure file to copy any files: 


dsave -s48 -i | ENTER 


@ This command operates in the same manner as the pre- 
vious command. However, because it specifies a procedure 
file pathlist, it stores the generated commands in a proce- 
dure file rather than displaying them on the screen: 


dsave -s48 -i > copyfile (ENTER] 
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ECHO 


Syntax: echo text 


Function: Echoes text to the screen. 


Parameters: 


text The character or characters you type. 


Notes: 


@ Use ECHO to generate messages in shell procedure files or 
to send an initialization character sequence to a terminal. 


The text should not include punctuation characters used by 
the shell. 


@ The following example prints the message LISTING ERROR 
MESSAGES to the screen and lists the file SYS/errmsg to the 
printer as a background task. 


echo LISTING ERROR MESSAGES: list sys7 
errmsg >/p& (ENTER ] 


Examples: 


@ To display a message on the screen, type: 


echo This text is echoing [ENTER] 


@ To echo text to the console, type: 


echo >/term **WARNING DATA ON DISK WILL BE 
LOST 


e@ The following combines the ECHO and LIST commands to 
echo the entered text to the printer and to direct the con- 
tents of the Trans file to the printer. 


echo >/p LISTING OF TRANSACTION; list trans 
>/p & (ENTER } 
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ERROR 


Syntax: error errnumber [...] 


Function: Displays the text error message that corresponds 
with the specified OS-9 error number. 


Parameters: 


errnumber Is an OS-9 error code in the range 1-255. 


Notes: 


@ ERROR opens the Errmsg file in the SYS directory and 
reads through the file for an error code that matches the 
specified number. It then displays the text that corresponds 
to the error code. 


@ The Errmsg file contains descriptions of the standard OS-9 
errors. The order of the file is arranged to provide quick 
access to operation system error descriptions. 


Example: 
e@ To display a description of the OS-9 error Numbers 215 and 
216, type: 
error 215 216 
The screen displays: 


215 - Bad Path Name 
216 - Path Name Not Found 
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KX 


Syntax: ex filename 


Function: Starts a process by chaining from the current shell 
to the new process. Chaining means that execution control is 
turned over to the new process. 


Parameters: 
filename The name of the program or module you want 
to execute. 
Notes: 
@ Because EX is a built in Shell command, it does not appear 


6-44 


in the CMDS directory. 


Using EX causes the shell from which you are operating to 
terminate. If the new process also terminates and you do 
not have another shell running on another terminal or win- 
dow, OS-9 is left without any processes, and you must 
reboot your computer and OS-9. 


If a shell is running on another window or device, you can 
restart a new shell from that window or device. For 
instance, if you use EX to initialize BASICO9 from /TERM 
then exit BASICO9, /TERM is dead and cannot accept key- 
board input. However, if you also have a shell operating in 
a window, you can type the following from that window: 


shell i=/termé 


This reinitializes a shell on /TERM. It can now accept key- 
board input and OS-9 commands. 


Use EX to save memory when the shell is not needed, for 
instance when using BASICO9. 


System Command Descriptions / 6 


@ If you use EX on a command line with other commands, it 
must be the last command. Any commands following EX 
on™ are not processed. 


Example: 


@ To run BASICO9 without a resident shell, type: 
ex basic09 
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FORMAT 


Syntax: format devname [name] [opts] © 


Function: Establishes and verifies an initial file structure on 
a floppy diskette or a hard disk. You must format all disks 
before you can use them on an OS-9 system. 


Parameters: 

devname The drive name of the disk you want to 
format. 

name The name you want to assign the newly for- 
matted disk. Enclose the disk name in double 
quotation marks. 

opts One or more of the following options. 

Options: 

l Writes system format information only, does 
not physically format disk. 

r Causes the format to proceed automatically, 
without issuing prompts. 

1 Formats single-sided. Use with single-sided 
drives or single-sided diskettes in double-sided 
drives. 

Z Causes a double-sided format. Use with 
double-sided drives and double-sided diskettes. 

‘cylinders’ The number of cylinders (in decimal) that you 
want formatted. 

:interleave: The number of the sector interleave value (in 


decimal). 
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Notes: 


@ Be sure the disk you want to format is NOT write- 


protected. Otherwise, FORMAT generates error code #242 
(write protect), and the system returns to the OS-9 prompt 
without formatting the diskette. 


If you are formatting a hard disk, first type: 
tmode -pause 


This command turns off the screen pause function. Other- 
wise, the process stops whenever the sector verification pro- 
cess fills the display screen. If you forget to turn off the 
screen pause, press the space bar whenever the screen fills. 
Execution then continues. 


When formatting finishes, type: 
tmode pause 


This re-establishes the screen pause function. 
The formatting process works this way: 


1. FORMAT physically initializes a disk and divides 
its surface into sectors. 


2. FORMAT reads back and verifies each sector. If a 
sector fails to verify after several attempts, FOR- 
MAT excludes it from the initial free space on the 
diskette. As verification proceeds, the process dis- 
plays track numbers. 


3. FORMAT writes the disk allocation map, ROOT 
directory, and identification sector to the first few 
sectors of Track 0. These sectors must not be 
defective. 


FORMAT asks for a disk volume name, which can be up to 
32 characters long and can include spaces or punctuation. 
(Later, you can use the FREE command to display the 
name.) 


6-47 


OS-9 Commands Reference 


@ For step-by-step instructions on formatting, refer to Getting 
Started With OS-9. 


Examples: 


@ To format a diskette in Drive /D1, type: 


format /d1 


@ To format a diskette in Drive /D1 with the name Test Disk 
and without prompts, type: 


format /d1 r “test disk" (ENTER] 
@ To format hard Disk /HO, type: 


tmode -pause [ENTER 
format /h@ | ENTER 
tmode pause [ENTER 


@ To format a double-sided diskette in Drive /D2 with 27 cyl- 
inders and the name Database, type: 


format /d1 2 "database" ‘277% [ENTER] 
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FREE 


Syntax: free [devname] 


Function: Displays the number of unused sectors (256-byte 
storage areas) on a disk drive. These sectors are available for 
new files or for expanding existing files. 


Parameters: 
devname The disk drive for which you want to display 
the number of free sectors. 
Notes: 


@ The device name you specify must be a disk drive. FREE 
also displays the disk’s name, creation date, and cluster 
size. If you don’t specify a drive, FREE selects the drive 
that contains the current data directory. 


@ The cluster size for the Color Computer is one sector. 


Examples: 


@ To display the number of free sectors on the current disk, 
type: 


free | ENTER 
The screen is similar to this: 


“COLOR COMPUTER DISK’’ created on: 83/05/28 
Capacity: 638 sectors (1-sector clusters) 
15 Free sectors, largest block 12 sectors 


@ To display the number of free sectors on the diskette in 
Drive /D1, type: 


free /d1 
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A sample screen display is: | 
"DATA DISK" created on: 83/06/16 
Capacity: 638 sectors Cli-seetor clusters? / | 
440 Pree sectors, lergest clock 442 Sectors | 
| 
| 
| 

ww 
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HELP 


Syntax: help [command name) [-?] 


Function: Displays the use and syntaxes of OS-9 commands. 


Parameters: 
command The command(s) for which you want help. 
name Include as many command names as you want. 
-? Gives a list of help topics. 

Notes: 


@ HELP uses a file named Helpmsg, which is located in the 
SYS directory on your system diskette. 


Examples: 


@ To obtain help for the BACKUP command, type: 
help backup 


The screen displays: 


Syntax: backup Cel(slj€-vJldevildev] 
Usage: Copies all data from one device to 
another 


e If you try to obtain help for a non-existent command, HELP 
displays an error message. For instance, if you type: 


help me (ENTER) 


me: no help available 
@ You can also obtain help for the HELP command. To do so, 
type: 
help help 
The screen displays: 


syntax: Help Csubject]{[-7] 
Usage: Give on-line help to users 

Will prompt if no subjects given 
Uptat =-% give List of néloe. topics 
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IDENT 


Syntax: ident filename [opts] 


Function: Displays header information for memory modules. 


Parameters: 
filename The name of the file or module for which you 
want to view identification information. 
opts One or more of the following options. 
Options: 
-m Causes IDENT to assume that filename is a 
module in memory 
-V Tells IDENT not to verify module cyclic redun- 
dancy check 
-X Causes IDENT to assume that filename is in 
the execution directory 
-S Displays the following module information on a 
single line: the edition byte (first byte after 
module name), the type/language byte, the 
module CRC and the module name. A period 
(.) indicates that the CRC verifies. A question 
mark (?) indicates that the CRC does not 
verify. 
Notes: 


@ IDENT displays the module size, CRC bytes (with verifica- 
tion), and—for program and device driver modules—the exe- 
cution offset and the permanent storage requirement bytes. 
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@ IDENT displays and interprets the type/language and 
attribute revision bytes. IDENT displays the byte immedi- 
ately following the module name because most Microware®- 
supplied modules set this byte to indicate the module 
edition. 


@ IDENT displays all modules contained in a disk file. 
Examples: 


@ To display header information for a file named Ident that 
resides in computer memory, type: 


ident -m ident 
The screen might display: 


Header for: IDENT 

Module size:$96E7 #1767 
Module CRC: $54@8BB2 (Good) 

Hdr parity: $C9Q 


Exec. of Ff: $9230 #573 
Data Size: $899C #24690 
EQi tion: $97 #7 


Ty/La At/Rv:$11 $81 
Prog mod, 6889 ob), re-en, R/O 


In the example, Hdr parity = header parity; Exec. off = 
execution offset; Data size = permanent storage require- 
ments; Edition = first byte after module name; Ty/La At/ 
Rv = type/language attribute/revision; and Prog mod, 
6809 obj, re-en = module type, language, attribute. 


@ To display header information for the OS9Boot file,type: 
ident /D#@/0S9boot -s 
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The display might include: 


17 $C 
67 $C@ 
12 $C1 
27 $D1 
6 $E1 
82 $F 1 
82 $F 1 
82 $F1 
11 $D1 
14 $E1 

1 $C1 

3 $C1 
Sa er 
83 $F 1 
83 $F 1 
83 $F 1 
83 $F 1 
83 $F 1 
83 $F 1 
83 $F 1 
83 $F 1 
Pe 
82 $Fi1 
12° SET 
83 $F 1 

4 $D1 

2 $E1 
80 $F1 
9 $C1 

3 $11 


Since the -s 


first line of the output, for instance, 17 = 
(first byte after name), $CO = 


$F2922F 
$Q@B2322 
S2ESEDE 
$BE65E3 
$0555890 
$FC1918 
$9F 4210 
$E6B118 
$1BA3FA 
$8524F 1 
$B53D94 
$792B/7E 
$ABSAES 
$7AB2DB 
$C3E38A 
$948878 
$36016B 
$BAE2BE 
$123B9A 
$1CF164 
$B71DF5 
$C8F073 
$9E655D 
$CC3EA4 
$FESBAE 
$AD6718 
$SB2B56 
$CCOGAF 
$BES3F 4 
$CAIF9SI 


OS9pe 
Init 
TOMan 
RBF 
CC3Disk 
Dg 

D1 

DD 

SGr 
CC3I10 
VDGInt 
GrtTiIat 
TERM 

W 

W1 

We 

W3 

W4 

WS 

W6 

W7 
ACIAPAK 
Te 
PRINTER 
a 
PipeMan 
Piper 
Pipe 
Clock 
CC3G0 


option appears in the command line, IDENT 
displays each module’s information on a single line. In the 


edition byte 
type/language byte, 


$A366DC = CRC value, . = OK CRC check, and OS9p2 = 
module name. 
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INIZ 


Syntax: iniz devname [...| 
Function: Initializes the specified device driver. 


Parameters: 


devname The name of one or more devices to initialize. 


Notes: 


@ You can use INIZ in the Startup file or at the system start- 
up to initialize devices and allocate their static storage at 
the top of memory to reduce memory fragmentation. 


e INIZ attaches the specified device to OS-9, places the device 
address in a new device table entry, allocates the memory 
needed by the device driver, and calls the device driver ini- 
tialization routine. INIZ does not reinitialize a device that 
you or the system previously installed. 


e If you change the printer (/p) to a non-shareable device (a 
device that is not re-entrant), do not initialize it with INIZ. 


Examples: 


@ To initialize the /P (printer) and /T2 (terminal 2) devices, 
type: 


ini O12 LENTER 


6-55 


OS-9 Commands Reference 


KILL 


Syntax: kill procID 


Function: Terminates the process specified by procID. 


Parameters: 


procID The ID number of the process to kill. 


Notes: 


@ Unless you are the Super User (User Number 0), you can 


only terminate a process that has your user number. (Use 
PROCS to obtain the process ID numbers.) The Super User 
can terminate any process. 


If a process is waiting for I/O, you cannot cancel it until the 
current I/O operation terminates. Therefore, if you KILL a 
process and PROCS shows it still exists, it is probably wait- 
ing to receive a line of data from a terminal. 


Because KILL is a built-in shell command, it does not 
appear in the CMDS directory. 


Examples: 


To KILL the process with the ID number 5, type: 


kill 5 (ENTER) 


The following commands: (1) use PROCS to determine that 
the ID number of the process to be killed is 3, (2) termi- 
nate process 3, and (3) use PROCS to confirm that KILL 
has cancelled the process. 
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procs LENTER 


User 
Id PId Number Pty Age 


@ 128 128 
0 128 128 
8 128 128 
0 128 129 


kill 3 LENTER 
procs LENTER 


User 
Id PId Number Pty Age 


2 8 128 128 
3. 4 0 128 128 
5 O @ 128 129 


Sts Signl Siz Ptr 


ots Sign! Siz Ptr 


Mem Stack 


3 $78B2 Shell 
2 $74AC Tsmon 
6 $05F3 Procs 
3 $6FE2 Shell 


Mem Stack 


3 $78B2 Shell 
6 $05F3 Procs 
3 $6FE2 Shell 


Primary Module 


Primary Module 
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LINK 


Syntax: link modname 
Function: Locks a previously loaded module into memory. 


Parameters: 


modname The name of the memory module to link. 


Notes: 


@ If the module is not already in memory, you must use 
LOAD prior to using LINK. The link count of the module 
increases by one each time the system links it. Use 
UNLINK to unlock the module when you no longer need it. 


Examples: 


@ To lock the Edit module into memory, type: 
link edit 
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LIST 


Syntax: list filename [...] 


Function: Lists the contents of a text file or files. 


Parameters: 
filename The name of the file you want to list. Include 
as many filenames on one line as you want, up 
to the maximum line length of 199 characters. 
Notes: 


e LIST copies text lines from a file to the standard output 
path. The program terminates upon reaching the end-of-file 
of the last input path. If you specify more than one file, 
LIST copies the files in the order in which you list them. 


@ Use LIST to examine or print text files. 


@ Do not LIST executable files. Doing so can cause your sys- 
tem to lock or crash. To view executable files, use DUMP. 


Examples: 


@ To list the contents of the Startup file to the printer, type: 
list /d@/startup >/pé 


The ampersand makes the printing job a concurrently exe- 
cuted task. 


@ To list three files to the screen, type: 


list /di/userS/document /d@/myfile /d@/ 
bob/text [ENTER] 


@ To copy everything you type at the keyboard to the printer, 
type: 


list /term >/p 
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To go back to the standard output path (the video display) 
press (CTRL }{ BREAK }. 


@ The following commands create a file called Animals, con- \_y | 
sisting of six entries. LIST, with the filename Animals as a 
parameter, displays the contents of the new file. 


build animals 
? cat [ENTER] 

cow CENTER} 

dog (ENTER) 
elephant [ENTER] | 
bird (ENTER | | 
fish (ENTER) | 
| 


list animals | ENTER | 


The screen displays: 


cat 

cow 

dog 
elephant 

bird | 
fish | 
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LOAD 


Syntax: load pathlist 
Function: Loads a module (program) from a file into memory. 


Parameters: 


pathlist Specifies the module to load. 


Notes: 


@ LOAD opens the path you specify, then loads into memory 
one or more modules from it. The process adds the names of 
the new modules to the module directory. If LOAD finds 
that a specified module has the same name and type as a 
module already in memory, it keeps the module with the 
highest revision level. 


e@ If the pathlist for LOAD does not include a drive name, 
LOAD uses the current execution directory. To LOAD a 
module from a directory other than the current execution 
directory, specify a full pathlist, beginning with a drive 
name if applicable. 


Examples: 


@ In the following example, MDIR displays the names of mod- 
ules currently resident in memory. Then, LOAD loads the 
Edit module into memory. MDIR again lists memory mod- 
ules, and this time shows that Edit is successfully added to 
memory. 


mdir | ENTER 
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The screen display is similar to the following: 


Module Directory at 12249252 


REL 
TOMan 
DD 
TERM 
W4 

T2 
rips 
Shell 
Dir 
List 
Procs 
Basicd@9 


Boot 
RBF 

SUF 

W 

WS 
PRINTER 
Clock 
Copy 
Display 
Load 
Rename 
GrT Dry 


load edit 


mdir 
The screen displays: 


Module Directory 


REL 
TOMan 
DD 
TERM 
W4 

Tz 
Pipe 
Shell 
Dir 
List 
Procs 
Basicd9 


Boot 
RBF 

SCF 

W 

WS 
PRINTER 
Clock 
Copy 
Display 
Load 
Rename 
GrfDrv 


US 2p! 
CC3Disk 
Cc3io 
W1 

WG 

P 
CC3Go 
Date 
EChs 
MDir 
Setime 


Usope 
D@ 
VDGInt 
We 

W7 
PipeMan 
CC3HDisk 
DelIniz 
Iniz 
hlerge 
Tmode 


at: Vee5172e12 


OS9p1 
CC3Disk 
CCSIG 
W1 

WG 

Pp 
CC3Go 
Date 
Echo 
MDir 
Setime 
Eqit 


US spe 
Dd 
VDGInt 
We 

W7 
PipeMan 
CC3HDisk 
DelIniz 
Inik2 
Merge 
Tmode 


Init Gao 


D1 
GrfInt 
W3 
ACIAPAK 
riper 
H@ 

Del 
Link 
Mfree 
Unlink 


Past 
D1 
GrfiInt 
W3 
ACIAPAK 
ramer 
H@ 

Del 
Link 
Mfree 
Unlink 
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MAKDIR 


Syntax: makdir pathlist or dirname 


Function: Creates a directory according to the pathlist given. 
You must have write permission for the parent directory of the 
directory you are creating. 


Parameters: 
pathlist The path to the directory you want to create. 
dirname The name of the directory you want to create. 
Notes: 


@ When MAKDIR initializes the new directory, the directory 
contains only the “.” and “..” files. 


@e MAKDIR enables all permissions for the directory it 
creates. 


@ To follow OS-9 convention, capitalize all directory names. 


Examples: 


@ To create a directory on Drive /D1, use the directory’s full 
pathlist from the root, such as: 


makdir /d1/STEVE/PROJECT (ENTER) 


@ To create a directory called DATAFILES within the current 
data directory, type: 


makdir DATAFILES [ENTER] 


@ To create a directory called SAVEFILES in the parent of 
the current directory, type: 


makdir ../SAVEFILES 


ee 


I 
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MDIR 


Syntax: mdir [e] 


Function: Displays the names of modules currently in mem- 
ory. MDIR automatically adjusts its output for 32- or 80- 
column displays. 


Options: 


e Causes a full listing of the extended physical 
address (block number and offset within the 
block), size, type, revision level, re-entrant 
attribute, user count, and name of each mod- 
ule. MDIR shows numbers in hexadecimal. | 
The display adjusts for 80 or 32 columns. | 


Notes: 


@ Many of the modules displayed by MDIR are OS-9 system 
modules and are not executable as programs. Always 
check the module type code before running a module 
with which you are not familiar. 


Examples: 


e Because MDIR adjusts to either 32 or 80 columns, the fol- 
lowing command produces a full module listing in either 
format: 


mdir e 
The 80-column display of MDIR e is: 
Module Directory at 03:03:53 WZ 


Block Offset Size Typ Rev Attr Use Module Name 


SF 


Ww 
am] 


1DO 
EDS 
CA1 
2E 
bo 
122B 
476 
30 
30 
30 
SB6 
B91 
CE? 
BF 
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C1 
Co 
Co 
Co 
C1 
DI 
Et 
Ff 
F 
ri 
Dt 
Et 
C1 
C1 
F 4 
Ff 
F 
Ff 
F 
F 
F 
F 
F 
E1 
F 
Et 
F 1 
D1 
Et 
Ff 
C1 
11 
11 
11 
I 
14 
11 
11 
11 
11 
11 
11 
14 
11 
11 


se ae | => ie “s “+s => er | ee hae 2 “+ ie | bap ae xy: “+ ae | 7s me _) ae ae ~s _) a “sy = “s+ “Ss “— = 
. . . . . . . e . . . . . . . J . . . ° . . s . o . . . . . J 


ee a | a : -) ee oe = “Ss i i) a =“ “Ss . 
. a . e e °. . . . ° . . . 


ovo wWoOvwWdnanswseaea ese @&@ @ oO —- — VU Pw BS S&S PMP rw 


—_ —«_—> «> 
—-" 22 O~nnen mee 2B Ww —- — Pw PMP PP 


Boot 
0S9p1 
OS9pe 
Init 
10Man 
RBF 
CC3Disk 
DO 

D1 

DD 

SCF 
Cc310 
VDGInt 
GrfInt 
TERM 
W 

W 1 

W2 

W3 


ACIAPAK 
T2 
PRINTER 
P 
PipeMan 
Piper 
Pipe 
Clock 
CC3Go 
Shell 
Copy 
Date 
DelIniz 
Del 

Dir 
Display 
Echo 
Iniz 
Link 
List 
Load 
MDir 
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@ The 32-column display of MDIR is: 
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onan MM M 


12EB 
tJos 
Lage 
1857 
1974 
1A8C 
1D8D 


68 
1EB 
319 
11D 
118 
301 

2D 


1 
{ 
{ 
1 
{ 
{ 
1 


—_> ——& —-> — > ———> |=-——-> -——-> 


—*& |b = BD =O =P =D =D 


Ta! Ue ee oS, ey we oS 


Merge 
Mfree 
Procs 
Rename 
Setime 
Tmode 
Unlink 


— ee — ee — ee —— ee —— ee | 


Module Directory at 93:96:49 


Blk Otst Size Ty Kyat Uc 


ar 
SF 
SF 


DOG 
E30 
1800 
rom) 
EA 1 
ECF 
1862 
2A8D 
2eF 83 
233 
2FPGS 
eras 
3549 
40DA 
4DC1 
3298S 
S9FS 
5A3A 
SA7D 
SACO 
5B8@3 
5B46 
5B89 
SBCC 
SCOF 
SFC4 
6003 
617D 
61B9 
63De2 
63FA 
6420 


12A 
1D0 
ED? 
CA1 
roa 
ga BO 
eeu 
476 
30 
38 
38 
SB6 
B91 
CE 7 
BFe 
45 
42 
43 
43 
43 
43 
43 
43 
43 
SBS 
SF 
17A 
3C 
i os, 
28 
26 
174 


C1 
C1 
CQ 
CQ 
CQ 
C1 
D1 
ea 
F 4 
F 4 
ra 
D1 
ET 
C1 
C1 
F 4 
F 4 
a 
a 
F 4 
F 4 
F 4 
ea 
F 4 
E.1 
F 4 
E 1 
ra 
D1 
E 4 
F 4 
C1 


te ce cree en eee ee ee a. i @ @ mn ee) 


r 


eS a SD ee Ie RT ea ee a er SS SS OS Sr Se a EY Br Ss Se eS 


Name 


7 
m™ 
rm 


Boot 
OS9p1 
OS 9pe2 

| hi Ba 
TOMan 
RBF 
CC3Disk 
Dg 

D1 

DD 

SCF 
CC3sio 
VDGInt 
Grt Int 
TERM 

W 

W1 

We 

W3 

W4 

WS 

WE 

W7 
ACIAPAK 
T2 
PRINTER 
Pp 
PipeMan 
FaIper 
Pipe 
Chock 


vOoOwWrPruUusaanaasasaso--wUoU A BANN AB - -—- B- B 


ss as: as 
—- NH NW NP 


————— 


Noonan gn aA MH HOA HMM HHMNNMNHNHHNHN DD = 


1AA 
SF2 
2DC 
FD 
76 
AS 
365 
84 
22 
6A 
2c 
4F 
24 
OF 1 
68 
1EB 
319 
11D 
118 
301 
2D 
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11 
14 
11 
1 
1 1 
ie 
11 
“7 
+] 
11 
11 
11 
iy 
11 
11 
11 
11 
11 
11 
11 
11 


— om or ora o-_-2 —2& =— —2 = -—2 —2 — 2 -——2 -—2 -——& -——& -——2 -——2 -— — -—— 


AO. TS OF SS Sa RS RS a Oe 


N]Qnunnoonaoae® ase oaoowowvaneooeneF828 2 WwW - 


CC3Go 
Shell 
Copy 
Date 
DEIniz 
Del 
Dit 
Display 
Echo 
Iniz 
(oEnk 
List 
Load 
MDir 
Merge 
Mfree 
Procs 
Rename 
Setime 
Tmode 
Unlink 
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MERGE 


Syntax: merge [filenamell...] 


Function: Copies files to the standard output path. By redi- 
recting the output of the MERGE command, you can combine 
several files into one file, or direct several files to the printer. 


Parameters: 


filename Specifies the files to combine. 
Notes: 


@ Use MERGE to combine several files into a single output 
file. It copies data in the order in which you type the 
filenames. 


@ MERGE does not output line editing characters (such as “Y/Y | 
the automatic line feed). 


@ You normally use MERGE with the standard output redi- 
rected to a file or device. 


@ You can use MERGE to append or copy any type or mix- 
ture of files to another device. 


Examples: 


@ To merge four files into a new file called Combined.file, and 
send the results to the new file instead of to the video dis- | 


play, type: | 


merge file! file2 file3 file4 >»combined.file 


@ To merge two files, and send the output to the printer, type: 


merge compile.list asm.list >/P (ENTER] 
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MFREE 


Syntax: mfree 


Function: Displays a list of memory areas not presently in use 
and, therefore, available for assignment. 


Notes: 


e MFREE displays the block number, physical (extended) 
beginning and ending addresses, and the size of each con- 
tiguous area of unassigned RAM. It gives the size in num- 
ber of blocks and in kilobytes. The block size is 8 kilobytes 
per block. Free memory for user data areas does not need to 
be contiguous because the MMU can map scattered free 
blocks to be logically contiguous. 


o 


Examples: 


@ Type this command: 
mfree 
The screen shows a display similar to this: 


Blk Begin End Blks Size 


10 12000 1@OFFF 1 8K 
18 18000 1DFFF 3 24K 
20 20000 3FFFF 16 128K 

Total: 20 160 
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MODPATCH 


Syntax: modpatch [options] filename [options] 


Function: modifies modules residing in memory. MODPATCH 
reads a patchfile and executes the commands in the patchfile 
to change the contents of one or more modules. 


Parameters: 
filename The name of a file containing instructions for 
MODPATCH 
options One of the following options that change MOD- 
PATCH’s function 
Options: 
-S Silent mode, does not display patchfile com- 
mand lines as they are executed. 
-w Does not display warnings, if any 
-C Compares only, does not change the module 
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@ Before using MODPATCH, you must create a patchfile to 
supply the data to control MODPATCH’s operation. This file 
contains single-letter commands and the appropriate mod- 
ule addresses. The commands are: 


1 modulename 


c offset origual rewval 


Link to the module specified 
by modulename. 


Change the byte at the offset 
address specified by offset from 
the value specified by origval 
to the new value specified by 
newval. If the original value 
does not match origval, MOD- 
PATCH displays a message. 


Verify the module—update the 
modules CRC. If you plan to 
save the patched module to a 
file that the system can load, 
you must use this command. 


Mask IRQ’s. Turns off inter- 
rupt requests (for patching 
service routines). 


Unmask IRQ’s. Turns on inter- 
rupt requests (for patching 
service routines). 


@ You can use the BUILD command or any word processing 


program to create patchfiles. 


@ Module byte addresses begin at 0. MODPATCH changes 
values pointed to by an offset address (offset from 0) rather 
than an absolute memory address. 
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To view the contents of a memory module, use SAVE and 
DUMP to copy the module to a file and display its contents. 
Also use SAVE to copy the patched module to a disk file. 


Changing a memory module might not produce an immedi- 
ate effect. You have to duplicate the initialization procedure 
for that module. This means, if the module loads during 
bootup, you have to create a new boot file that includes the 
changed module, then reboot using the new boot file. 


To use the patched module in future system boots, use 
SAVE to store the module in the MODULES directory of 
your system disk. You can then use OS9GEN to create a 
new system disk using the patched module. If you are 
using the patched module to replace another module, 
rename the original module and then give the patched 
module the original name. 


If you patch a module that is loaded during the system 
boot, you can use COBBLER to make a new system boot 
that uses the patched module. 


Examples: 


The following example shows the commands, the screen prompts, 
and the entries you make to patch the standard 40-column term 
window descriptor to be an 80-column screen rather than the 
standard 40-column screen: 
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OS9:build termpatch (ENTER ] 
? I term [ENTER] 

2? c¢ 002c 28 50 [ENTER] 

7 ¢ 0030 01 O02 

? v (ENTER ) 

? CENTER } 


0S9: modpatch termpatch 
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To change the size, columns, and colors of Device Window W1, 
create the following procedure file and name it W180: 


I wt 

¢ 0030 07 O02 
e 002¢ 1b 50 
oe 002d 06 18 


If the W1 module is not already in memory, load it from the 
MODULES directory of your system disk. Then, before initializ- 
ing W1, run MODPATCH: 


modpatch w180 
Next, initialize W1: 


iniz wt _|ENTER 
shell i=/w/1& | ENTER 


Press to display the new window with 80 columns, 24 
lines, and a white background. 
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MONTY PE 


Syntax: montype type 


Function: Sets your system for the type of monitor you are 


using 
Parameters: 
Parameters: 
type A single letter indicating the monitor type: 
c for composite monitors or color televisions 
r for RGB monitors 
m for monochrome monitors or black and 
white televisions 
Notes: 


e Different types of color monitors display colors differently. 
For the best results, set your system to the type of monitor 
you are using. 


e If you are using a monochrome monitor or black and white 
television, you can obtain a sharper image by setting your 
monitor type to monochrome. 


® Include the MONTYPE command in your system’s Startup 
file to automatically boot in the proper monitor mode. 


e@ If you do not use MONTYPE, the system defaults to c (com- 
posite monitor). 


Example: 


To set your system for an RGB monitor, type: 


montype r [ENTER 
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To add a MONTYPE command to your existing Startup file, first 
use BUILD to create the new command. For example: 


build temp [ENTER 
montype r [ENTER 
ENTER 


Next, append the file to Startup. Type: 
merge startup temp > startup.new 
Delete the temp file: 


del temp 


To enable the system to use Startup.new when booting, rename 
the original Startup file: 


rename Startup Startup.old 
Then rename Startup.new: 


rename Startup.new Startup 
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OSIGEN 


Syntax: os9gen devname [opts] 


Function: Creates and links the required OS9Boot file to a 
diskette making it a bootable diskette. 


Parameters: 


deuname 


opts 
Options: 


=5 


#n[K] 


Notes: 


The disk drive containing the diskette to 
receive the new boot file. 


One or more of the following options. 


Causes OS9GEN to use only one drive to gen- 
erate the boot file. In a single-drive operation, 
OS9GEN reads the modules from the source 
diskette and asks you to exchange diskettes 
and press as it reads and copies the 
modules. 


reserves n kilobytes of memory for use by the 
OS9GEN command. By setting aside as much 
memory as possible, you can increase the 
speed of OS9GEN and, on single-drive sys- 
tems, reduce the number of diskette swaps. If 
you type K after #n, the memory specified by 
n is in kilobytes (1024 bytes), otherwise n is 
in 256-byte pages. 


@ OS9Boot files can only exist on contiguous sectors. There- 
fore, use OS9GEN only with newly formatted diskettes. If 
OS9Boot is fragmented, the system warns you not to use 
the diskette to bootstrap OS-9. 
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@ OSIGEN creates a working file called Tempboot on the 
device specified by deuname. Next, it reads filenames (path- 
lists) either from the keyboard (the standard input path) or 
redirected from a file. If you enter names manually, 
OS9GEN does not display a prompt. Type each filename 
and press (ENTER). After typing the last filename and press- 


ing (ENTER), press (ENTER] again, or press (CTRL [BREAK] to com- 
plete the list. 


OS9GEN opens each file and copies it to Tempboot. The 
process repeats until it reaches a blank line or an end-of- 
file marker. All of the modules listed in Chapter 5 are not 
required in a boot file. These modules must be included in 
a boot File: 
OS9p2, Init, IOMan, RBF, SCF, CC3IO, VDGInt (or 
GrfInt), CC3Disk, DO, TERM, Clock, CC3GO0. 


@ You must have RENAME in the current execution directory 
or in memory for OS9GEN to work properly. 


@ With all input files copied to Tempboot, OS9GEN deletes 
the OS9Boot file, if it exists. It renames Tempboot as 
OS9Boot, and writes the file’s starting address and size in 
the diskette’s Identification Sector (LSN 0) for use by the 
OS-9 bootstrap firmware. OS-9 writes its kernel on diskette 
Track 34. If there is not room for the kernel, an error mes- 
Sage appears, and the operation terminates. 


e@ If you have only one drive, you can generate a new boot file 
more easily using the CONFIG utility. CONFIG is 
designed to make custom system diskettes using either sin- 
gle- or multiple-drives. 


Examples: 


@ The following commands manually install a boot file on 
device /D1 that is an exact copy of the OS9Boot file on 
device /DO. The first command line runs OS9GEN, the sec- 
ond enters the name of the file to install, and the third 
enters an end-of-file marker. 


o5s9gen /d1 
/d@/os9boot [ENTER 
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@ The following commands let you manually install a boot file 
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on device /D1 that is a copy of the OS9Boot file on device 
/DO and the modules stored in the files /D0/Tape.driver and 
/D2/Video.driver. Line 1 executes OS9GEN. Line 2 enters 
the main boot filename. Lines 3 and 4 enter the names of 
the two additional files, and Line 5 enters an end-of-file 
marker. 


os9gen /d1 
/d@/os9boot 
/d@/tape.driver 
/d2/video.driver 


The following commands generate a new boot file on Drive 
/D1 that includes all the old boot file modules. Line 1 uses 
BUILD to create a file called Bootlist. The next three lines 
enter the names of the three files into Bootlist. Line 5 ter- 
minates BUILD, and Line 6 runs OS9IGEN with input 
redirected from the new Bootlist file. 


build /d@/bootlist 

? /d@/os9boot 

? /d@/tape.driver (ENTER } 

? /d@/video.driver [ENTER] 

? 

os9gen /d1</d0/bootlist [ENTER] 


To install a custom boot file on a single-drive system, build 
a Bootlist to drive the OS9GEN program. You need a direc- 
tory that contains the required file managers, device driv- 
ers, descriptors, and other files for the boot file. For 
example, to make a new boot file containing only the 
/TERM, /DO, /D1, and /P devices, first build a Bootlist such 
as: 
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build /d@/bootlist 
term—vdg.dt 
p. dd [ENTER] 
d@_35s5.dd (ENTER ] 
d1__35s.dd (ENTER) 
9 s9p2 (EATER) 

Init 

I OMan (ENTER | 

RBF .mn 
CC3Disk.dr [ENTER] 
SCF .mn 
CC3I0.dr (ENTER) 
vdgint.io 
printer.dr 
clock.6@hz 
ce3go (ENTER) 


Then use OS9GEN to create the new boot file on a separate 
diskette by typing: 


o59gqen /d@ -s #25K </d@/bootlist [ENTER] 


This command causes OS9GEN to use only one drive, 25K 
of buffer space, and the filenames previously stored in the 
Bootlist file. 


You can expand this basic bootlist file to include other stan- 
dard OS-9 modules such as window device descriptors, other 
disk drivers, descriptors, and terminal or modem 
descriptors. 


All of the standard bootlist modules are contained in the 
MODULES directory on the BASICO9/CONFIG diskette. 
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PROCS 


Syntax: procs [e] 


Function: Displays a list of the processes running on the sys- 
tem. PROCS automatically adjusts its output for 32-or 80- 
column displays. 


Options: 
a Causes PROCS to display the processes of all 
users. 
Notes: 


@ Normally PROCS lists only processes having the user’s ID. 
The list is a snapshot taken at the instant PROCS exe- 
cutes. Processes switch states rapidly, usually many times 
per second. 


@ PROCS shows the user and process ID numbers, priority, 
state (process status), memory size (in 256 byte pages), pri- 
mary program module, and standard input path. 


@ PROCS adjusts its output for 80 or 32 columns. 
Examples: 


@ Because PROCS automatically adjusts for either 32- or 80- 
column displays, the following command can produce either 
format: 


procs e [ENTER 
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Following is a possible 32-column display of PROCS: 


sere Fty 


Ste or 


Age Sta 
Primary 


id Pid Uv 
Sigl Mem 

2 1 
") 2 

3 =) 
) LS 

4 2 
) 6 

5 9 
") 3 

6 1) 
0 3 


MY 
$6F Be 

128 
$68E2 


128 $80 
Shell 
128 $80 
Basicd9 
128 $80 
Procs 
128 $80 
Shell 
129 $80 
Shell 


Following is a possible 80-column display of PROCS: 


User 


Id PId Number Pty Age Sts Signl Siz Ptr 


Mem Stack 
Primary Module 


128 128 $88 
128 128 $80 
128 128 $80 
128 129 $80 
128 129 $88 
128 128 $80 


3 $78B2 Shell 
16 $74B2 Basic09 
3 $72E2 Shell 
3 $6FB2 Shell 
3 $68E2 Shell 
6 $05F3 Procs 
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PWD 
PXD 


Syntax: pwd 
pxd 


Function: PWD shows the path from the ROOT directory to 
the current data directory. PXD shows the path from the 
ROOT directory to the current execution directory. 


Notes: 


@ OS-9 keeps a current data directory and current execution 
directory for each process. Use PWD and PXD to show 
where your current data and execution directories are 
located on the disk or disks you are using. 


Examples: 
@ The following example uses a full pathlist. CHD changes 

the current data directory to the MANUALS directory. 
chd /d1/steve/textfiles/manuals 

To display the full path to the data directory, type: 
pwd 

The screen displays the data directory path: 
FDIS STEVESTEXTF PLES/MANUALS 


@ The following commands cause the current data directory 
to move up one level in the directory hierarchy and then 
display the data directory. 


chd .. (ENTER 
pwd (ENTER 


/DISSTEVEZTEXTFILES 
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@ The following commands change the current data directory 
to the parent directory and then display the current data 
directory. 


chd .. (ENTER 
pwd (ENTER 


J/OTZISTEVE 


@ The following command displays the current execution 
directory, CMDS. 


pxd [ENTER 


/DO/CMDS 
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RENAME 


Syntax: rename pathlist filename 


Function: Gives the specified file or directory a new name. 


Parameters: 
pathlist The current name of the file or directory. 
filename The new name. 

Notes: 


@ You must have write permission for the file. 
Examples: 


@ To change a file’s name from Blue to Purple, type: 
rename blue purple 

e@ To rename a file in the USER9 directory of Drive /D3, type: 
rename /d3/user9/test temp 


@ In the following example, DIR displays the names of the 
files in the current data directory. RENAME changes the 
filename Animals to Mammals. Another DIR command 
shows that RENAME has performed properly. 


dir 
The screen displays: 


Directory of . 16:22:53 
myfile animals 


rename animals mammals | ENTER 
dir | ENTER 
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The screen now shows: 


Directory of «= tTtez23122 
myfile mammals 
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SETIME 


Syntax: setime [yy/mm/dd hh:mn\:ss]] 


Function: Sets the system date and time, and activates the 
real time clock. 


Parameters: 
yy The year in a two-digit format (86 for 1986). 
mm The month in a one or two-digit format (01 or 
1 for January, 12 for December). 
dd The day of the month in a one- or two-digit 
format, such as 21. 
hh The hour in a one- or two-digit, 24-hour for- 
mat (15 for 3 p.m.). 
mm Minutes in a one- or two-digit format, such as 
03, 5, or 55. 
Ss Seconds in a one- or two-digit format, such as 
04, 5, or 25. 
Options: 


Specifying seconds in the new time entry is optional. 
Notes: 


@ You can include the date and time parameters. If you do 
not, SETIME asks you for them. 


@ Numbers are one- or two- decimal digits using the space, 
colon, semicolon, or slash as delimiters. 


@ The CC3go module starts the clock on system startup, so 
multitasking is possible without use of the SETIME utility. 
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@ If you do not set the date and time when booting OS-9, the 


system cannot accurately update the “Last modified” date 
fn and time for files. 


Examples: 
@ To set the date and time to August 15, 1986, 3:45 p.m., 
type: 


setime 86,08,15,15,45 


@ To set the same date using a slightly different but equally 
acceptable format, type: 


setime 86/08/15 15/45/90 
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SETPR 


Syntax: setpr procID number 


Function: Changes the CPU priority of a process. The priority 
of a process determines the CPU time allotted to it under 
multi-tasking conditions. 


Parameters: 
procID The number of the process for which you want 
to change the priority. 
number The new priority number. 
Notes: 


@ The process priority number is a decimal number in the 
range 1 (lowest priority) to 255. If you need information 
about the process ID number and current priority, use 


PROCS. 


@ You can use SETPR only on processes that have your user 
number. 


@ SETPR does not appear in the CMDS directory because it 
is built into the shell. 


@ A Super User (User 0) can set any process priorities. 


Examples: 


@ To set or change the priority of Process 8 to 250, type: 
setpr 8 250 
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@ In the following commands PROCS displays process ID 
numbers and other information. Then, SETPR sets Process 
3 to a priority of 255. The final command confirms the 
change. 


procs [ENTER 


Following is a sample screen display: 


User 
Id PId Number 


Pty Age 


Sts Signl Siz Ptr 


Mem Stack 


Primary Module 


| 6 128 128 $80 3 $78E2 Shell 

3 «6 § 128 128 $89 0 16 $74B2 BasicO9 

4 2 6 128 128 $80 6 $05F3 Procs 

ee | 6 128 128 $89 3 $6FB2 Shell 

6 6 § 128 129 $80 3 $68E2 Shell 
setpr 3 255 
procs 

User Mem Stack 


Id Pld Number Pty Age Sts Signl Siz Ptr Primary Module 
i a 0 128 128 $8¢ 3 $78B2 Shell 
3. 6 @ 255 128 $88 6 16 $74B2 Basic9 
4 65 @ 128 128 $80 3 $72E2 Shell 
5 0 128 129 $86 3 $6FB2 Shell 
6 6O 0 128 129 $89 0 3 $68E2 Shell 
7, 4 @ 128 128 $80 0 6 $05F3 Procs 
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SHELL 


Syntax: = shell arglist 


Function: The shell is OS-9’s command interpreter program. It 
reads data from its standard input path, processes it and 
sends the output to its standard output path, and sends error 
messages (and some prompts) via the standard error output. 
Any or all of these paths may be redirected. It interprets the 
data as a sequence of commands. The function of the shell is 
to initiate and control execution of other OS-9 programs. 


Parameters: 
arglist The commands, parameters, and options given 
SHELL in a command line. 
Notes: 
@ The shell reads and interprets one text line at a time from 


the standard input path until it reaches an end-of-file 
marker. At that time it terminates itself. 


When another program calls the shell, a special case occurs 
in which the shell takes the argument list as its first line 
of input. If this command line consists of built-in com- 
mands only, the shell reads and processes more lines. Oth- 
erwise, control returns to the calling program after the 
shell processes the single command line. 


When operating from the shell, you do not need to specify 
the SHELL command to execute a program, a command, or 
a built-in shell function. Using SHELL before a command 
causes the existing shell to fork an additional shell, which 
then forks the specified process, such as: 


shell dir e 


Issuing a command without SHELL causes the existing 
shell to fork the specified process, such as: 


dir e [ENTER 
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The following two commands also have identical effects: 


shell x {ENTER 
x | ENTER 


@ The shell command separators are: 


& 


Sequential execution separator 
Concurrent execution separator 
Pipeline separator 


end-of-line (sequential execution separator) 


@ The Shell command modifiers are: 


bP 


Redirect standard input 

Redirect standard output 

Redirect standard error output 

Redirects standard input and standard output 


Redirects standard input and standard error 
output 


Redirects standard output and standard error 
output 


<>>> Redirects standard input, standard output and 


standard error output 


#n Set the process memory size in pages 

#nK Set the program memory size in 1 kilobyte units. 
@ The following built-in Shell command parameters tell OS-9 

to: 
chd pathlist Change the data directory 
kill procID Send the termination signal to 
process 
setpr proclD Change the specified process 
number priority 


6-91 


OS-9 Commands Reference 


chx pathlist Change the execution directory 

i = devicename Create an immortal process 

Ww Wait for any process to die 

p Turn on prompting 

-p Turn off prompting 

t Echo input lines to standard output 
-t Not echo input lines 

-X Not terminate on an error 

x Terminate on error 

. Not process the following text 


@ See Chapter 3 for more information on the operation of the 
shell. 
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TMODE 


Syntax: tmode [pathnum] [paramlist) [...] 


Function: Displays or changes the initialization parameters of 
the terminal. TMODE automatically adjusts its output for 32- 
or 80-column displays. 


Common uses include changing baud rates and control key 
definitions. 


Parameters: 
pathnum One of the standard path numbers: 
.0 = standard input path 
.1 = standard output path 
.2 = standard error output path 
paramlist One of the following options. 
Options: 
upc Displays uppercase characters only. Lowercase 
characters automatically convert to uppercase. 
-upe Displays both upper- and lowercase characters. 
bsb Causes a backspace to erase characters. Back- 
space characters echo as a backspace-space- 
backspace sequence. This setting is the system 
default. 
-bsb Causes backspace not to erase. Only a single 
backspace echoes. 
bsl Enables backspace over a line. Deletes lines by 


sending backspace-space-backspace sequences 
to erase a line (for video terminals). This set- 
ting is the system default. 


-bsl 


echo 


-echo 


pause 


eof=h 
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Disables backspace over a line. To delete a line, 
TMODE prints a new line sequence (for hard- 
copy terminals). 


Input characters echo on the terminal. This 
setting is the system default. 


Turns off the echo default. 


Turns on the auto line feed function. Line 
feeds automatically echo to the terminal on 
input and output carriage returns. The auto 
line feed setting is the system default. 


Turns off the auto line feed default. 


Sets the null count—the number of null ($00) 
characters transmitted after carriage returns 
for the return delay. The value n is in decimal. 
The default is 0. 


Turns on the screen pause. This setting sus- 
pends output when the screen fills. See the 
pag parameter for a definition of screen size. 
Resume output by pressing the space bar. This 
setting is the system default. 


Turns off the screen pause mode. 


Sets the length of the video display page to n 
(decimal) lines. This setting affects the pause 
mode. 


Sets the backspace character for input. The 
value A is in hexadecimal. The default is 08. 


Sets the delete line character for input. The 
value fh is in hexadecimal. The default is 18. 


Sets the end-of-record (carriage return) char- 
acter for input. This setting requires a value 
in hexadecimal. The default is OD. 


Sets the end-of-file character for input. The 
value /A is in hexadecimal. The default is 1B. 


reprint = h 


dup=h 


psc=h 


abort =h 


quit=h 


bse=h 


bell=h 


type=h 


System Command Descriptions / 6 


Sets the reprint line character. The value h is 
in hexadecimal. 


Sets the character to duplicate the last input 
line. The value h is in hexadecimal. The 
default is 01. 


Sets the pause character. The value of the 
character is in hexadecimal. The default is 17. 


Sets the terminate character (normally CON- 
TROL C). The value of the character is in 
hexadecimal. 


Sets the quit character (normally CONTROL 
E). The value of the character is in 
hexadecimal. 


Sets the backspace character for output. The 
value h is in hexadecimal. The default is 08. 


Sets the bell (alert) character for output. The 
value fh is in hexadecimal. The default is 07. 
For external devices, use type for ACIA (asyn- 
chronous communications interface adapter) 
initialization values (hexadecimal). The 
default is 00. Bits 5-7 set either MARK, 
SPACE, or no parity on all devices. Codes for 
these are: 


000 = no parity 
101 = MARK parity transmitted, no 
checking 


111 = SPACE parity transmitted, no 
checking 


O11 = even parity (available only with 
the external ACIA pak and Mod- 
pak devices) 


001 = odd parity (available only with 
the external ACIA pak and Mod- 
pak devices) 
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xon=h 


xoff = h 


baud =h 
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Bit 4 selects auto-answer modem support fea- 
tures. 


1S 
0 = off 


See “Technical Information for the RS232 
Port” in Chapter 5 for more information. 


For TERM-VDG, the type byte has a different 
use: 


Bit 0 specifies a machine with true low- 
ercase capability. Set Bit 0 to turn on 
true lowercase. 


For TERM-WIN, use a value of 80 to specify a 
window device. 


Sets the character to be used as a signal for 
resuming transmission of data after an xoff 
signal is received. Default is 0 (not active). 


Sets the character to be used for stopping data 
transmission. Default is 0 (not active). 


Sets the baud rate, word length, and stop bits 
for a software-controllable interface. The codes 
for the baud rate are: 


0=110 3=1200 6= 9600 
1=300 4=2400 7=19200 (ACIAPAK only) 
2=600 5=4800 7=32000 (SIO only) 


Bits 0-3 determine the baud rate. 
Bit 4 is reserved for future use. 
Bits 5-6 determine the word length: 


00 = 8 bits 
01 = 7 bits 
Bit 7 determines the number of stop bits: 
0 = 1 stop bit 
1 = 2 stop bits 


See “Technical Information for the RS232 
Port” in Chapter 5 for further information. 
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Notes: 


You can specify any number of parameters from the options 
list, separating them by spaces or commas. If you don’t 
specify parameters, TMODE displays the current values of 
the available options. 


You can use a period and a number to specify the pathnum- 
ber on which to read or set options. If you don’t specify a 
path, TMODE affects the standard input path. 


TMODE works only if a path to the file/device is open. Use 
XMODE to alter device descriptors and set device initial 
operating parameters. 


TMODE can also alter the baud rate, word length, stop 
bits, and parity for devices already initialized. 


If you use TMODE in a procedure file, you must specify one 
of the standard output paths (.1 or .2). This procedure is 
necessary, because the command redirects the SHELL’s 
standard input path to come from a disk file. (You can use 
TMODE only on SCFMAN-type devices.) For example, to 
set lines per page for standard output, use this line: 


TMODE .1 pag=24 (ENTER ] 


Examples: 


The following command line sets the terminal to display 
upper- and lowercase, sets the null count to 4, and turns on 
the screen pause function. 


tmode -upc lf null=4 pause [ENTER] 


The next command sets the screen page length (number of 
lines) to 24, turns on the screen pause function and the 
backspace-over-line function, and sets the backspace charac- 
ter value to 8 and turns off the echo default. 


tmode pag=24 pause bsl -echo bsp=8 (ENTER) 
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TUNEPORT 


Syntax: tuneport [device] [-s= value] 


Function: Lets you test and set delay loop values for the cur- 
rent baud rate and select the best value for your printer or 
terminal. 


Parameters: 
device The device you want to test, either your 
printer (/p) or terminal (/t1). 
value A new delay loop value. 
Options: 
-S= Sets a new delay loop value. 
Examples: 


@ The following command provides a test operation for your 
printer. 


tuneport /p 


After a short delay, TUNEPORT displays the current baud 
rate and sends data to the printer to see if it is working 
properly. The program then displays the current delay value 
and asks for a new value. Enter a decimal delay value and 
press (ENTER]. Again, TUNEPORT sends data to the printer 
as a test. Continue this process until you find the best 
value. When you are satisfied, press instead of enter- 
ing a value at the prompt. A closing message displays your 
new value. 


Use the same process to set a new delay loop value for the 
/T1 terminal. 
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@ The following command line sets the delay loop value for 
your printer to 255. 


tuneport /p -s=255 


Use such a command on future system boots to set the opti- 
mum delay value determined with the TUNEPORT test 
function. Then, using OS9GEN or COBBLER, generate a 
new boot file for your system diskette. You can also use the 
-s option with TUNEPORT in your system Startup file to 
set the value. 


6-99 


OS-9 Commands Reference 


UNLINK 


Syntax: unlink modname [...] 


Function: Tells OS-9 that the named memory module(s) is no 
longer needed by the user. 


Parameters: 


modname One or more modules you want to unlink. 
Options: 


In one command line, you can specify as many modules as you 
want to unlink. 


Notes: 


@ Whether OS-9 destroys the modules and reassigns their 
memory depends on whether the module is in use by other 
processes. Each process using a module increases its link- 
count by one. Each UNLINK you issue decreases its link- 
count by 1. When the link-count reaches 0, OS-9 deallo- 
cates the module. 


@ You should unlink modules whenever possible to make most 
efficient use of available memory resources. Modules you 
have loaded and linked might need to be unlinked twice to 
remove them from memory. 
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@ Warning: Never attempt to unlink a module you didn’t load 
or link, and never unlink a module that is in use by pro- 
grams (displayed by the PROCS command). 


Examples: 


@ To unlink three modules named Pgm1, Pgm5, and Pgm99, 
type: 


unlink pgm1 pgm5 pgm99 [ENTER] 


@ In the following command sequence, MDIR first displays 
the modules in memory. The next command unlinks the 
edit module. The output of the final command (MDIR) 
shows that UNLINK is successful—Edit no longer appears 
on the list. 


mdir 
A possible screen display is: 


Module Directory at 00:01:08 


REL Boot OS9p1 OS9p2 Init 
TOMan RBF CC3Disk DO D1 

DD SCF CC310 VDGInt Grf Int 
TERM W W1 W2 W3 

W4 WS WG W7 ACIAPAK 
T2 PRINTER P PipeMan Piper 
Pipe Clock CC3Go CC3HDisk H@ 
Shell Copy Date DEIniz Del 
Dir Display Echo Iniz Link 
List Load MDir Merge Mfree 
Procs Rename Setime Tmode Unlink 
Basic09 GrfDrv Edit 


unlink edit | ENTER 
mdir | ENTER 
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The new screen display is: 


Module Directory at 00:03:15 


REL 
I0Man 
DD 
TERM 
W4 

T2 
Pipe 
Shell 
Dir 
List 
Procs 
BasicQ9 


Boot 
RBF 

SCF 

W 

WS 
PRINTER 
Clock 
Copy 
Display 
Load 
Rename 
GrfDrv 


0S9p1 
CC3Disk 
CC310 
W 1 

WG 

; 
CC3G0 
Date 
Echo 
MDir 
Setime 


OS9p2 
oy 
VDGInt 
We 

W7 
PipeMan 
CC3HDisk 
Delniz 
Iniz 
Merge 
Tmode 


Init 
D1 
GrfInt 
W3 
ACIAPAK 
Piper 
HO 

Del 
Link 
Mfree 
Unlink 
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WCREATE 


Syntax: wcreate /wpath [-s=type] xpos ypos xsize 
ysize foreground background [border] 


Function: Initializes and creates a window. 


Parameters: 


/wpath 
xpos 
ypos 


xsize 


ysize 


foreground 
background 
border 


Options: 


-S = type 


The window device name of the window you 
are creating (W, W1, W2, W3, and so on). 


The x co-ordinate (in decimal) for the starting 
position of the upper left corner of the screen. 


The y co-ordinate (in decimal) for the starting 
position of the upper left corner of the screen. 


The horizontal size of the screen in columns; 1 
to 80 (in decimal) for screen types 2, 5, and 7, 
and 1 to 40 (decimal) for screen types 1, 6, 
and 8. 


The vertical size of the screen in lines, in the 
range 1 to 24 (in decimal). 


The window foreground color. 
The window background color. 


An optional window border color. The default 
is black. 


The screen type, chosen from the following 
list: 


Type Description 


1 = 40-column hardware text screen 
i 80-column hardware text screen 
= 640 x 192 two-color screen 
6 = 320 x 192 four-color screen 
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640 x 192 four-color screen 
320 x 192 sixteen-color screen 


7 
8 


If you use the -s=type option, you must spec- 
ify a border color in the command line. The -s 
option is only used to create a window on a 
new screen. When creating additional windows 
on the currently displayed screen, omit the -s 
and border color options. 


4 Directs WCREATE to accept input from the 
standard input (redirected from a file). 


-? Produces a help message for the command. 
Examples: 


@ To create a full screen, 80-column text window on /wl, 
type: 


wereate /w1 -s=2 @ @ 88 24 7 4 1 [ENTER] 


@ To create two windows (/w2 and /w3) on a 640 x 192 graph- 
ics screen in which /w2 is the upper left of the display and 
/w3 is the right half of the display, first use build to create 
an input file: 


build wfile (ENTER] 

? /w2 -s=07 0 0 40 12 7 4 1 (EMER) 
2 /w3 40 0 40 24 4 7 (ENTER) 

? (ENTER) 


Then, create the windows using Wfile as input: 


wereate -z « wfile/|ENTER 
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@ You can use the -z option to create windows in your system 
startup file. For example, the following startup file sets up 
fr» several windows, along with the usual SETIME. 


* Lock. the shell in memory and set the time 
link shell 
setime < /1 


* create the new windows 

wereate -z 

* set up an 8@-column full window for /wi 
/wi -s=2 0 80 88 24 7 4 1 

* set up a 48 column full window for /we 
/we -5s=1 0 0 40 24 7 4 1 

* set up /w3 anda /w4 as nalves of « 

4040 x 192 display 

/w3 -5=7 0 @ 480 24 7 4 1 

/w4 40 @ 40 24 4 7 

* the following blank line terminates input 
* from wcreate 


* get the graphics fonts loaded 
merge sys/stdfonts > 7w 
Now, when the system boots, it has four windows defined, 
besides TERM. As shown, you can use an asterisk as the 
first character on a line in order to allow comments in the 
file. 
ff’ 
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XMODE 


Syntax: xmode devname [paramlist] 


Function: Displays or changes the initialization parameters of 
any SCF-type device such as the video display, printer, 
RS-232 port, and others. XMODE automatically adjusts its 
output for 32- or 80-column displays. 


Common uses include changing baud rates and control key 


definitions. 


Parameters: 


pathnum 


paramlist 
Options: 


upc 


-upc 
bsb 


-bsb 


bsl 


-bsl 


The device name to change, such as /term, 
/w7, /t2, and so on. 


One of the following options. 


Displays uppercase characters only. Lowercase 
characters automatically convert to uppercase. 


Displays both upper- and lowercase characters. 


Causes a backspace to erase characters. Back- 
space characters echo as a backspace-space- 
backspace sequence. This setting is the system 
default. 


Causes backspace not to erase. Only a single 
backspace echoes. 


Enables backspace over a line. Deletes lines by 
sending backspace-space-backspace sequences 
to erase a line (for video terminals). This set- 
ting is the system default. 


Disables backspace over a line. To delete a line, 
you must print a new line sequence (for hard- 
copy terminals). 
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echo 


-echo 


pause 


eof=h 


reprint =h 


dup=h 
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Input characters echo on the terminal. This 
setting is the system default. 


Turns off the echo default. 


Turns on the auto line feed function. Line 
feeds automatically echo to the terminal on 
input, and they output carriage returns. The 
auto line feed setting is the system default. 


Turns off the auto line feed default. 


Sets the null count—the number of null ($00) 
characters transmitted after carriage returns 
for the return delay. The value n is in decimal. 
The default is 0. 


Turns on the screen pause. This setting sus- 
pends output when the screen fills. See the 
pag parameter for a definition of screen size. 
Resume output by pressing the space bar. This 
setting is the system default. 


Turns off the screen pause mode. 


Sets the length of the video display page to n 
(decimal) lines. This setting affects the pause 
mode. 


Sets the backspace character for input. The 
value fh is in hexadecimal. The default is 08. 


Sets the delete line character for input. The 
value fh is in hexadecimal. The default is 18. 


Sets the end-of-record (carriage return) char- 
acter for input. This setting requires a value 
in hexadecimal. The default is OD. 


Sets the end-of-file character for input. The 
value fh is in hexadecimal. The default is 1B. 


Sets the reprint line character. The value A is 
in hexadecimal. 


Sets the character to duplicate the last input 
line. The value hf is in hexadecimal. The 
default is 01. 


6-107 


OS-9 Commands Reference 


psc=h 


abort =h 


quit=hA 


bse=h 
bell=h 


type=h 


6-108 


Sets the pause character. The value of the 
character is in hexadecimal. The default is 17. 


Sets the terminate character (normally CON- 
TROL C). The value of the character is in 
hexadecimal. 


Sets the quit character (normally CONTROL 
E). The value of the character is in 
hexadecimal. 


Sets the backspace character for output. The 
value fh is in hexadecimal. The default is 08. 


Sets the bell (alert) character for output. The 
value A is in hexadecimal. The default is 07. 


For external devices, use type for ACIA (asyn- 
chronous communications interface adapter) 
initialization values (hexadecimal). The 
default is 00. Bits 5-7 set either MARK, 
SPACE, or no parity on all devices. Codes for 
these are: 


000 = no parity 


101 = MARK parity transmitted, no 
checking 


111 = SPACE parity transmitted, no 
checking 


011 = even parity (available only with 
the external ACIA pak and Mod- 
pak devices) 


001 = odd parity (available only with 
the external ACIA pak and Mod- 
pak devices) 


Bit 4 selects auto-answer modem support fea- 
tures. 


1 = on 
0 = off 


See “Technical Information for the RS232 
Port” in Chapter 5 for more information. 


baud=h 


xon =h 


xoff=h 
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For TERM-VDG, the type byte has a different 
use: 


Bit 0 specifies a machine with true low- 
ercase capability. Set Bit 0 to turn on 
true lowercase. 


For TERM-WIN, use a value of 80 to specify a 
window device. 


Sets the baud rate, word length, and stop bits 
for a software-controllable interface. The codes 
for the baud rate are: 


0=110 3=1200 6= 9600 

1=300 4=2400 7=19200 (ACIAPAK 
only) 

3=600 5=4800 7=82000 (SIO only) 


Bits 0-3 determine the baud rate 
Bit 4 is reserved for future use 
Bits 5-6 determine the word length: 


00 = 8 bits 
01 = 7 bits 
Bit 7 determines the number of stop bits: 
0 = 1 stop bit 
1 = 2 stop bits. 


See “Technical Information for the RS232 
Port” in Chapter 5 for further information. 


Sets the character to be used as a signal for 
resuming transmission of data after an xoff 
signal is received. Default is 0 (not active). 


Sets the character to be used for stopping data 
transmission. Default is 0 (not active). 
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Notes: 


XMODE is similar to TMODE, but there are differences. 
TMODE operates only on open paths, so its effect is tempo- 
rary. XMODE updates the device descriptor. Its change per- 
sists as long as the computer is running, even if you or the 
system repeatedly open and close the paths to the device. 


If you use XMODE to change parameters and the COB- 
BLER program to make a new system diskette or to re- 
make the boot tracks on the current system diskette, the 
process permanently changes the parameters on the new 
system diskette. 


XMODE requires that you specify a device name. If you do 
not specify parameters, XMODE displays the present value 
for each parameter. You can use any number of parameters, 
separating them with spaces or commas. 


Examples: 
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The following command sets the term (video) for upper- and 
lowercase, the null count to 4, the backspace character 
value to 1F hexadecimal, and turns on the screen pause 
function. 


xmode /term -upc null=4 bse=1F pause (ENTER] 
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Macro Text Editor 


Overview 


The OS-9 Macro Text Editor is a powerful, easy-to-learn text- 
preparation system. Use it to prepare text for letters and docu- 
ments or text to be used by other OS-9 programs, such as the 
assembler and high-level languages. The text editor includes the 
following features: 


@® Compact size 


® Capability of having multiple read and write files open 
at the same time 


@ All OS-9 commands usable inside the text editor 
@ Adjustable workspace size 
@® Repeatable command sequences 
a @ Edit macros (special utility functions) 
@ Multiple text buffers 
@ Powerful commands 


The Macro Text Editor is about 5 kilobytes in size and requires 
at least 2K bytes of free RAM to run. 


Text Buffers 


As you enter text, the editor places it in a temporary storage 
area called a text buffer. A text buffer acts as a scratch pad for 
saving text that you can manipulate with various edit com- 
mands. The Macro Text Editor can use multiple text buffers, one 
at a time. 


A buffer in use is called the edit buffer. Edit also has another 
default buffer called the secondary buffer. As well, you can create 
a additional buffers up to the capacity of your computer’s memory. 


Edit Pointers 


The Macro Text Editor has an edit pointer that identifies your 
position in the buffer, in a manner similar to holding your place 
in a book with your finger. 
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The pointer is invisible to you, but Edit commands can reposi- 
tion it and display the text to which it points. Each buffer has its 
own edit pointer, and you can move from buffer to buffer without 
losing your place in any of them. 


Entering Commands 


The Macro Text Editor is interactive. This means you and the 
editor carry on a two-way conversation. You issue a command, 
and the editor carries out the command and displays the result. 
When you are through making changes, you can save your 
edited file, then press (Q] to quit editing. 


When the editor displays E: on the screen, it is waiting for you 
to type a command. You type a line that includes one or more 
commands, then press [ENTER]. Edit carries out the commands and 
again displays E:. 


If you enter more than one command on a line, separate the 
commands with a space. If, however, a space is the first charac- 
ter on a line, the editor considers the space to be an insert com- 
mand and not a separator. 


Correct a typing error by backspacing over it or by deleting the 
entire line. Note, you cannot correct a line after pressing [ENTER]. 


Control Keys 


You can use the same special control keys with Edit that you 
use with OS-9. See Appendix D for a complete listing of these 
keys. Following is a list of some of the control keys that are espe- 
cially useful with Edit: 


Control Key(s) Function 

Repeats the previous input line. 

Terminates the editor and returns to com- 
mand entry mode. 

(0) Displays the current input on the next line. 

Backspaces and erases the previous 

or character. 
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Control Key(s) Function 
[a] Interrupts the editor and returns to com- 


mand entry mode. 


Temporarily halts the data output to your 
terminal so that you can read the screen 
before the data scrolls off. Output resumes 
when you press any other key. 


or Deletes the line. 


CTRL ) [ BREAK Terminates the editor, and returns to com- 
mand entry mode. 


Command Parameters 


There are two types of edit parameters, “numeric” and “string.” 


Numeric Parameters. Numeric parameters specify an amount, 
such as the number of times to repeat a command or the number 
of lines affected by a command. If you do not specify a numeric 
parameter, the editor uses the default value of one. Specify all 
other numeric parameters in one of the following ways. 


e Enter a positive decimal integer in the range 0 to 
65,535. For example: 


e@ Enter an asterisk (*) as a shorthand for all (all the way 
to the beginning, all the way to the end, all of the lines, 
and so on). To the editor, an asterisk means infinity. Use 
the asterisk to specify all remaining lines, all charac- 
ters, or repeat forever. 


@ Use a numeric variable. (See “Parameter Passing” later 
in this chapter.) 
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String Parameters. String parameters specify a single charac- 
ter, group of characters, word, or phrase. Specify string parame- 
ters in either of the following ways. 


@ Enclose the group of characters with delimiters (two 
matching characters). You can use any characters, but 
they must match. If one string immediately follows 
another, separate the two with a single delimiter that 
matches the others. For example: 


"String of cnearacters” 
/STRING/ 

: ny neanhie! Ta Larry + 

“fitest String second String” 
PRTPING 12 String. 27 


e@ Use a string variable. (See “Using Macros” later in this 
chapter.) 


Syntax Notation 


Syntax descriptions indicate what to enter and the order in 
which to do it. The command name is first; type it exactly as 
shown. Follow the command name with the correct parameters. 
Enter each as it is described in the section on parameters. 


The syntax descriptions for each command use the following 
notations: 


n = numeric parameter 

str = string parameter 

(] = space character. When you see ||, press the space bar. 
text = one or more characters terminated by pressing 


Getting Started 
From the OS-9 prompt, start Edit by typing: 


edit {ENTER 
Enter a command when the screen shows E:. 


You can quit Edit at any time by pressing (Q) (ENTER). The Q com- 
mand terminates the editor and returns you to the OS-9 Shell, 
which responds with the 0S9: prompt. 
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Following is a list of ways you can start the editor, including the 
effect of each. The examples call a file that already exists oldfile. 
They call a file to be created new/file. 


EDIT 


EDIT newfile 


EDIT oldfile 


EDIT oldfile 
newfile 


OS-9 loads the editor and starts it. The com- 
mand does not establish an initial read or 
write files, but you can perform text file opera- 
tions by opening files after the editor is 
started. 


OS-9 loads the editor and starts it, creating 
the file called newfile. Newfile is the initial 
write file. There is no initial read file. How- 
ever, you can open files to read later. 


OS-9 loads the editor and starts it. The initial 
read file is oldfile. The editor creates a file 
called SCRATCH as the initial write file. 
When you end the edit session, OS-9 deletes 
oldfile and renames SCRATCH to oldfile. This 
gives the appearance of oldfile being updated. 


Note: The two OS-9 utilities DEL and 
RENAME must be present on your system if 
you wish to start the editor in this manner. 


OS-9 loads the editor and starts it. The initial 
read file is oldfile. The editor creates newfile— 
the initial write file. The terms oldfile and 
newfile refer to any properly constructed OS-9 
pathlist. 
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Edit Commands 


Displaying Text 


Ln 


Lists (displays) the next n lines, starting at 
the current position of the edit pointer. The 
edit pointer position does not change. 


1 [ENTER ) 


displays the current line. If the edit pointer is 
not at the beginning of the line, only the por- 
tion of the line to the right of the edit pointer 
shows on the screen. 


13 [ENTER J 


displays the current line and the next two 
lines. 


1 * CENTER } 


displays all text from the current position of 
the edit pointer to the end of the buffer. 


The L command displays text regardless of 
which verify mode is in effect. 


Displays the n lines that precede the edit 
pointer. The position of the edit pointer does 
not change. For example: 


x CENTER } 


displays any text on the current line that pre- 
cedes the edit pointer. If the edit pointer is at 
the beginning of the line, the command dis- 
plays nothing. 


x3 (ENTER) 


displays the two preceding lines and any text 
on the current line that precedes the edit 
pointer. 


The X command displays text regardless of 
which verify mode is in effect. 
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Manipulating the Edit Pointer 


CTRL or 
on an external 
terminal 


Moves the edit pointer to the beginning (first 
character) of the text buffer. The screen shows 
the up arrow when you hold down and 
press (7). For example, 


moves the edit pointer to the beginning of the 
buffer. 


Moves the edit pointer to the end (last charac- 
ter) of the buffer. For example, 


/ (ENTER } 


moves the edit pointer past the end of the 
buffer. 


Moves the edit pointer to the beginning of the 
next line and displays it. Use this command to 
go through text one line at a time. You can 
look at each line, correct any mistakes, and 
then move to the next line. 
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“nl 
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Moves the edit pointer either to the end of the 
line or forward n lines and displays the line. 
Entering a value of zero moves the edit pointer 
to the end of the current line. For example: 


*@ (ENTER ] 


Entering a value other than zero moves the 
pointer forward n lines and displays the line. 
For example, 


+ (ENTER ) 


moves the pointer to the next line and displays 
the line. This command performs the same 


function as [ENTER ). 
+1@ [ENTER 


moves the pointer ahead 10 lines and displays 
the line. 


oa 
moves the edit pointer to the end of the buffer. 


Moves the edit pointer either to the beginning 
of the line or backward n lines. For example: 


-@ (ENTER) 


moves the edit pointer to the beginning of the 
line and displays the line. Entering a value 
other than zero moves the edit pointer back n 
lines. For example, 


~ (ENTER ) 


moves the edit pointer back one line and dis- 
plays the line. 


~5 (ENTER } 


moves the edit pointer back five lines and dis- 
plays the line. 


~* (ENTER J 


moves the edit pointer to the beginning (top) 
of the buffer and displays the first line. 


>n 


<n 
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Moves the edit pointer to the right n charac- 
ters. Use this command to move the edit 
pointer to some position in the line other than 
the first character. For example, 


> (ENTER ) 


moves the edit pointer to the right one 
character. 


>25 | ENTER 


moves the edit pointer to the right 25 
characters. 


>* 
moves the edit pointer to the end of the buffer. 


Moves the edit pointer to the left n characters. 
Use this command to move the edit pointer to 
some position in a line other than the first 
character. For example: 


< (ENTER) 


moves the edit pointer to the left one 
character. 


<1 | ENTER 


moves the edit pointer to the left 10 
characters. 


<* (ENTER ] 


moves the edit pointer to the beginning of the 
buffer. 
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Inserting and Deleting Lines 


‘ltext 


In str 
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Preceding text lines with a space inserts the 
text as a new line ahead of the edit pointer. 
The position of the edit pointer does not 
change. For example, 


HInsert this line 


inserts the line. 


MLine one |ENTER 
(Line two | ENTER 
Line three | ENTER 


inserts three lines. 


Inserts a line of n copies of the specified string 
immediately before the position of the edit 
pointer. The position of the edit pointer does 
not change. For example, 


i40/+/ (ENTER) 


inserts a line containing 40 asterisks. You can 
also use the “I” command to insert a line con- 
taining a single copy of the string. This func- 
tion is important when you want to use a 
macro to insert lines, since the space bar can- 
not be used within a macro. For example, 


i“Line to insert" | ENTER 


inserts the line. 
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Deletes (removes) n lines from the edit buffer, 
starting with the current line. This command 
displays the lines to be deleted. For example: 


d (ENTER) 


deletes the current line, regardless of the posi- 
tion of the edit pointer, and displays it. 


d4 (CENTER } 


deletes the current line and the next three 
lines. 


d* CENTER } 


deletes everything from the current line to the 
end of the buffer. 


Kills (deletes) n characters, starting at the 
current position of the edit pointer. This com- 
mand displays all deleted characters. For 
example, 


k [ENTER } 


deletes the character at the edit pointer. 


k 4 (ENTER ) 


deletes the character at the current position of 
the edit pointer and the next three characters. 


k * [ENTER } 


deletes everything from the current position of 
the edit pointer to the end of the buffer. 


a a 


OS-9 Commands Reference 


En str 


Extends n lines by adding a string to the end 
of each line. — extends a line, displays it, and 
then moves the pointer past it. For example, 


e/this is a comment/ | ENTER 


adds the string “this is a comment” to the end 
of the current line and moves the edit pointer 
to the next line. 


e3/xx | ENTER 


adds the string xx to the end of the current 
line and the next two lines. It moves the 
pointer past these lines. 


Unextends (deletes) the remainder of a line 
from the current position of the pointer. Use U 
to remove extensions, such as comments, from 
a line. For example, 


u CENTER) 


deletes all the characters from the current 
position of the pointer up to the end of the cur- 
rent line. 


For some practice in using the commands that display text, 
manipulate the edit pointer, and insert and delete lines, turn to 
Sample Session 1 in this chapter. 
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Searching and Substituting 


Sn string 


Cn string 1 
string2 


Searches for the next n occurrences of string. 
When Edit finds an occurrence, it displays the 
line and moves the edit pointer to the line. If 
Edit does not find the string or if all the 
occurrences have been found, the edit pointer 
does not move. For example, 


s/my string’ ENTER 


searches for the next occurrence of “my 
string”. 


so Strung out | ENTER 


searches for the next three occurrences of 
“strung out”. 


s*/seek and find/ (ENTER 


searches for all occurrences of “seek and find” 
between the edit pointer and the end of the 
text. 


Changes the next n occurrences of stringl to 
string2. When Edit finds string1, it moves the 
edit pointer past it and changes stringl to 
string2, then it displays the updated line. If it 
does not find stringl it displays “NOT 
FOUND.” If all the occurrences have been 
found, the edit pointer does not move. For 
example, 


c/this/that/ 


changes the next occurrence of “this” to 
“that”, 


e27infsouts 


changes the next two occurrences of “in” to 
66 99 
out’. 

c*!seek and find!sought and 


found! | ENTER 


changes all occurrences of “seek and find” 
that are between the edit pointer and the end 
of text to “sought and found”. 
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Sets the SEARCH/CHANGE anchor to Col- 
umn n. To find a string that begins in a spe- 
cific column, set the anchor to the column 
position before using the search command to 
find it. If you do not include a value for n, Edit 
assumes Column 1. For example: 


a (ENTER) 


finds a string only if it begins in Column 1. 


a2@ | ENTER 


finds a string only if it begins in Column 20. 
If you use the A command to set the anchor, 
this setting remains in effect only for the cur- 
rent command line. After Edit executes the 
command, the anchor automatically returns to 
its normal value of zero. 


For some practice in using the commands that search and substi- 
tute, turn to Sample Session 2 in this chapter. 


Miscellaneous Commands 


Tn 
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Tabs (moves) the edit pointer to Column n of 
the current line. If n exceeds the line length, 
this command extends the line with spaces. 
For example, 


t CENTER) 


moves the edit pointer to Column 1 of the cur- 
rent line. 


tS (ENTER } 


moves the edit pointer to Column 5 of the cur- 
rent line. 


‘a 


SHELL 
command 
line 
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Lets you use any OS-9 command from within 
the editor. The remainder of the command line 
following .SHELL passes to the OS-9 Shell for 
execution. For example, 


.shell dir /d1 


calls the OS-9 Shell to display the directory of 
D1. 


~shell basic@9 
starts BASICO9. 


»shell edit oldfile newfile [ENTER] 
restarts the editor. 


Adjusts the amount of memory available for 
buffers and macros. If the workspace is full 
and the editor does not allow you to enter 
more text, increase the workspace size. If you 
need only a small amount of the available 
workspace, decrease the workspace size so that 
other OS-9 programs can use the memory. For 
example, — 


m5 00d 
sets the workspace size to 5000 bytes. 


m1000 
sets the workspace size to 10000 bytes. 


Before leaving Edit, you can increase the 
workspace. This decreases the time the editor 
takes to copy the input file to the output file, 
because the editor can read and write more 
data at one time. Edit changes memory in 
256-byte pages. For the M command to have 
any effect, a new workspace size must differ 
from the current size by at least 256 bytes. 
The M command does not let you deallocate 
any workspace that Edit needs for buffers or 
macros. 
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SIZE 


V mode 
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Displays the size of the workspace and the 
amount that has been used. For example: 


.51ze 


oe] 19328 


521 is the amount of workspace Edit uses for 
buffers and macros. 15328 is the amount of 
available memory. 


Ends editing and returns to the OS-9 Shell. If 
you specified files when you started, Edit 
writes the text in Buffer 1 to the initial write 
file (specified when you start Edit). Next it 
copies the remainder of the initial input file 
(specified when you start Edit) to the initial 
write file. The editor then terminates, and 
control returns to the OS-9 Shell. 


Turns the verify mode on or off. Edit always 
starts with the verify mode on. Therefore, the 
editor displays the results of all the commands 
for which verify is appropriate. If you do not 
want to see the results of commands, turn off 
the verify mode by specifying 0 (zero) for 
mode. To turn verify back on, specify any non- 
zero number. For example, 


vO (ENTER) 


turns off the verify mode. 


v2 (ENTER } 


turns on the verify mode. 


vi3 {ENTER 


turns on the verify mode. 


If the verify mode is on when you switch to a 
macro, it remains on. If you turn off verify 
while in the macro, it is restored when you 
return to the editor. 
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Manipulating Multiple Buffers 


a 
.DIR 
Bn 
Pn 
wn 


Displays the directory of the editor’s buffers 
and macros. For example: 


BUPPERS 
$ 8 (secondary buffer) 
1 (primary buffer) 
S (another buffer) 

MACROS: 

MYMACRO 

LIST 

COPY 


Makes buffer n the primary buffer. When you 
switch from one buffer to another, the old one 
becomes the secondary buffer, and the new one 
becomes the primary buffer. For example, 


bS (ENTER) 


makes Buffer 5 the primary buffer. If Buffer 5 
does not exist, Edit creates it. 


Puts (moves) n lines into the secondary buffer. 
This command removes the lines from the pri- 
mary buffer, starting at the position of the 
edit pointer, and inserts them into the second- 
ary buffer before the current position of the 
edit pointer. It displays the text that is moved. 
For example, 


p 

moves one line to the secondary buffer. 
ps 

moves five lines to the secondary buffer. 


p* CENTER ] 


moves all lines that are between the current 
position of the edit pointer and the end of text 
to the secondary buffer. 
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Gn 


Gets (moves) n lines from the secondary 
buffer. This command takes the lines from the 
top of the secondary buffer and inserts them 
into the primary buffer before the current 
position of the edit pointer. Edit then displays 
the moved lines. When used with the P com- 
mand, G moves text from one place to another. 
For example, 


g CENTER) 


gets one line from the secondary buffer. 


gS (ENTER) 


gets five lines from the secondary buffer. 


g* (ENTER) 


gets all lines from the secondary buffer. 


For some practice in using miscellaneous commands and the 
commands that manipulate multiple buffers, turn to Sample Ses- 
sion 3 in this chapter. 


Text File Operations 


This section of the manual describes the group of commands 
related to reading and writing OS-9 text files. 


.NEW 
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Gets new text. Use .NEW when editing a file 
that is too large to fit into the editor’s work- 
space. .NEW writes out all lines that precede 
the current line, then appends an equal 
amount of new text to the end of the buffer. 


.NEW always writes text to the initial output 
file (created when you start the editor) and 
always reads text from the initial input file 
(specified when you start the editor). 


If you have finished editing the text currently 
in the buffer, you can “flush” this text and fill 
the buffer with new text by moving the edit 
pointer to the bottom of the buffer and then 
using the .NEW command. For example: 


/.new | ENTER 


wy 


~-READ str 
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If you wish to retain part of the text that is 
already in the buffer, move the edit pointer to 
the first line you wish to retain and then type 
.new. This command “flushes” all lines that 
precede the edit pointer. It then tries to read 
in new text that is the same size as the por- 
tion flushed out. 


Prepares an OS-9 text file for reading. str 
specifies the pathlist. For example. 


spead. “mytiie” 


closes the current input file and opens 
“myfile” for reading. 


You can specify an empty pathlist. For 
example, 


read ‘| ENTER 


closes the current input file and restores the 


initial input file (specified when you start the 
editor) for reading. 


An open file remains attached to the primary 
buffer until you close the file. You can have 
more than one input file open at any time by 
using the .READ command to open them in 
different buffers. 


To read these files, switch to the proper buffer, 
and then use the R command to read from 
that buffer’s input file. To close a file, you 
must be in the same buffer where the file was 
opened. 
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WRITE str 


Opens a new file for writing. The string speci- 
fies the pathlist for the file you wish to create. 
For example, 


write “newfile" | ENTER 


closes the current write file and creates one 
called “newfile”. You can specify an empty 
pathlist. For example: 


write ‘'' | ENTER 


closes the current write file and restores the 
initial write file (specified when you start the 
editor). 


WRITE attaches a new write file to the pri- 
mary buffer that remains attached until you 
close the file. You can have more than one 
write file open by using .WRITE to open them 
in different buffers. To write these files, switch 
to the proper buffer. To close a file, you must 
be in the same buffer where the file was 
opened. 


Reads (gets) n lines of text from the buffer’s 
input file. It displays the lines and inserts 
them before the current position of the edit 
pointer. For example, 


r (ENTER } 


reads one line from the input file. 


r1Q 
reads 10 lines from the input file. 
r* 
reads the remaining lines from the input file. 


If a file contains no more text, the screen 
shows the «END OF FILE* message. 
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Writes n lines to the output file, starting with 
the current line. It displays all lines that are 
deleted from the buffer. For example, 


w CENTER J 


writes the current line to the output file. 


wS (ENTER } 


writes the current line and the next four lines 
to the output file. 


w* CENTER } 


writes all lines from the current line to the 
end of the buffer to the output file. 


For some practice in using the commands that read and write 
OS-9 text files, turn to Sample Session 4 in this chapter. 


Conditionals and Command Series Repetition 


When a command cannot be executed, the editor sets an internal 
flag, and the screen shows *FAIL*. For example, if you try to 
read from a file that has no more text, the editor sets the fail 
flag. A set fail flag means that the editor cannot execute any 
more commands until Edit encounters one of the following: 


@ The end of a command line typed from the keyboard. 


@ The end of the current loop. Any loops that are more 
deeply nested are skipped. (See the repeat command.) 


@ A colon (:) command. Since loops nested deeper than the 
current level are skipped, any occurrences of : that are 
in a more deeply nested loop are also skipped. 
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Following are the commands and conditions that set the fail flag: 


< Trying to move the edit pointer beyond the 
beginning of the edit buffer. 

> Trying to move the edit pointer beyond the + 
end of the buffer. 

S,C Not finding a string that was searched for. 

G No text left in the secondary buffer. 

R No text left in the read file. 


P,W No text left in the primary buffer. 


If you specify an asterisk for the repeat count on these com- 
mands, Edit does not set the fail flag, because an asterisk usu- 
ally means continue until there is nothing more to do. The 
following commands explicitly set the fail flag if some condition 
is not true. 


EOF Tests for end-of-file. EOF succeeds if there is 
no more text to read from a file. Otherwise, it 
sets the fail flag. 


.NEOF Tests for not end-of-file. .NEOF succeeds if 
there is text to read from the file. Otherwise, 
it sets the fail flag. 


-LKOB Tests for end-of-buffer. .EOB succeeds if the 
edit pointer is at the end of the buffer. Other- 
wise, it sets the fail flag. 


.NEOB Tests for not end-of-buffer. .NEOB succeeds if 
the edit pointer is not at the end of the buffer. 
Otherwise, it sets the fail flag. 


EOL Tests for end-of-line. This test succeeds if the 
edit pointer is at the end of the line. Other- 
wise, it sets the fail flag. 


.NEOL Tests for not end-of-line. .NEOL succeeds if 
the edit pointer is not at the end of the line. 
Otherwise, it sets the fail flag. 


ZERO n Tests for zero value. .ZERO succeeds if n 
equals zero. Otherwise, it sets the fail flag. 
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STAR n 


STR str 


.NSTR str 


[commands|n 
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Tests for star (asterisk). STAR succeeds if n 
equals 65,535 (“*”). Otherwise, it sets the fail 
flag. 


Tests for string match. .STR succeeds if the 
characters at the current position of the edit 
pointer match the string. Otherwise, it sets 
the fail flag. 


Tests for string mismatch. .NSTR succeeds if 
the characters at the current position of the 
edit pointer do not match the string. Other- 
wise, it sets the fail flag. 


Exits and succeeds. This is an unconditional 
exit from the innermost loop or macro. The 
fail flag clears after the exit. 


Exits and fails. This is an unconditional exit 
from the innermost loop or macro. The fail 
flag sets after the exit. 


Repeats the commands n times. Left and right 
brackets form a loop that repeats the enclosed 
commands n times. (The loop must be 
repeated at least once.) If you enter the loop 
command from the keyboard, it must all be on 
one line. If it is part of a macro, however, it 
can span several command lines. For example, 


[1] 5 (ENTER) 


repeats the L command five times. 


Note: This is not the same as L5, which executes the L 
command only once and has 5 as its parameter. 


bay 


Displays lines starting with the next line up 
to the end of the buffer and moves the edit 
pointer to the end of the buffer. 


This command repeats until the operation 
reaches the end of the buffer. Then, when the 
command tries to move the edit pointer past 
the end of the buffer, Edit sets the fail flag, 
terminates the loop, then clears the fail flag. 
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>: commands 
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Executes the commands following the colon 
based on the state of the fail flag. For 
example: 


FAIL FLAG CLEAR Skips all commands 
that follow the colon (:) 
up to the end of the cur- 
rent loop or macro. 


FAIL FLAG SET Clears the fail flag, and 
executes the commands 
that follow the colon (:). 


Below is a command line that deletes all lines 
that do not begin with the letter A. 


LOTRL IT) it qmeob: lh atrran 4-2 a9 
1 * (ENTER J 


(*] moves the edit pointer to the beginning of 
the buffer. The outer loop tests for the end of 
the buffer and terminates the loop when it is 
reached. 


The inner loop tests for A at the beginning of 
the line. If there is an A, the + command is 
executed. Otherwise, it executes the D 
command. 


Below is a command that searches the current 
line for “find it”. If the command finds the 
text, it displays the line. Otherwise, the com- 
mand line fails and the screen shows 
FP Atl. Sk, 


[> »,B@el ove =o vat £ oSte'tingd 2" 
-@ .5 : [>] ]* (ENTER) 


.EOL VO -0 V .F tests to determine if the edit 
pointer is at the end of the line. If it is, Edit 
turns off the verify mode to prevent -0 from 
displaying the line. Then it turns verify back 
on, and .F ends the loop. 


ed 
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If the edit pointer is not at the end of the line, 
the .STR command searches for “find it” at the 
current position of the edit pointer. If it is at 
the end of the line, Edit executes the -0 .S 
commands. This execution moves the edit 
pointer back to the beginning of the line, dis- 
plays the line, and terminates the loop. Other- 
wise, the > command moves the edit pointer 
to the next position in the line. 


The brackets prevent the command from fail- 
ing and terminating the main loop if the end 
of the buffer is reached. 


Edit Macros 


Edit macros are commands you create to perform a specialized 
or complex task. For example, you can replace a frequently used 
series of commands with a single macro. First, save the series in 
a macro. Then each time you need it, type a period followed by 
the macro’s name and parameters. The editor responds as if you 
had typed the series of commands. 


Macros consist of two main parts, the header and the body. The 
header gives the macro a name and describes the type and order 
of its parameters. The body consists of any number of ordinary 
commands. (Except for a space character and [ENTER], you can use 
any command in a macro). 


Note: Macros cannot create new macros. 


To create a macro, first define it with the .MAC command. Then 
enter the header and body in the same manner as you enter text 
into an edit buffer. When you are satisfied with the macro, close 
its definition by pressing (Q} (ENTER]. This command returns you 
to the normal edit mode. 


Macro Headers. A macro header must be the first line in each 
macro. It consists of a name, and a “variable list” that describes 
the macro’s parameters, if there are any. The name consists of 
any number of consecutive letters and underline characters. Fol- 
lowing are possible macro names: 


del_all 

trim_spaces 

LIST 
CHANGE_X_TO_Y 
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Although you can make a macro name any length, it is better to 
keep it short, because you must spell it the same way each time 
you use it. You can use upper- and lowercase letters or a 
mixture. 


Using Macros. Like other commands, you can give parameters 
to macros so that they are able to work with different strings 
and with different numbers of items. Macros are unable to use 
parameters directly. Instead, Edit passes the parameters on to 
the commands that make up the macro. 


To pass the macro’s parameters to these commands, use the 
variable list in the macro header to tell each command which of 
the macro’s parameters to use. Each variable in the variable list 
represents the value of the macro parameter in its corresponding 
position. Use the corresponding variable wherever the parame- 
ter’s value is needed. 


The two types of variables are numeric and string. A numeric 
variable is a variable name preceded by the # character. A 
string variable is a variable name preceded by a $ character. 
Variable names, like macro names, are composed of any number 
of consecutive letters and underline characters. Examples of 
numeric variables are: 


#N 
#ABC 
#LONG_NUMBER_VARIABLE 


Examples of string variables are: 


$lower_case_variable_name 


The function of the edit macro below is the same as that of the S 
command, to search for the next n occurrences of a string. 
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The first line of the macro is the macro header. It assigns the 
macro’s name as SRCH. It also specifies that the macro needs 
one numeric parameter (#N) and one string parameter ($STR). 
The entire body of the macro is the second line. This example 
passes both of the macro’s parameters to the S command, which 
does the actual searching. 


SRCH #N $STR 
S #N $STR 


Here is an example of how to execute this macro: 


/SRCH 75 “string” 


In the next example, the order of the parameter is reversed. 
Therefore, when executing the macro, use the reverse order. The 
macro structure is: 


SRCH $STR #N 
S #N $STR 


Specify the parameters for the “S” command in the proper order 
since it is only the “SRCH” macro that is changed. The following 
example shows how to execute this macro. The order of the 
parameters corresponds directly to the order of the variables in 
the variable list. 


.SRCH "string" 15 
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Macro Commands 


Although macro editing has the same functions as text editing, 
the macro mode also includes some special commands. The 
macro commands you can use are as follows: 


! text 


-macro name 


.MAC str 
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Places comments inside a macro. Ignores the 
remainder of the line following the ! command. 
This command lets you include, as part of a 
macro, a short description of what it does. 
Comments can help you remember the func- 
tion of a macro. For example: 


' 
<*>! Move the pointer to the top of the 


buffer. 
1*! Display all lines of text. 
' 


In this example there are four comments. Two 
are empty, and two describe the commands 
that precede them. 


Executes the macro specified by the name fol- 
lowing the period (.). For example: 


.mymacro (ENTER | 

list @ [ENTER] 

~trim ™ " (ENTER | 

.merge " file_a " file b b"™ [ENTER] 


Creates a new macro or opens the definition of 
an existing one so that it can be edited. To 
create a new macro, specify an empty string. 
For example, 


.~mac'''* | ENTER 


creates a new macro and puts you into the 
macro mode. 


SAVE str1 
str2 


SEARCH n 
str 
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The screen shows M: instead of E: when the 
editor is in the macro mode. To edit a macro 
that already exists, specify the macro’s name. 
For example, 


.mac "mymacro"™ 
opens the macro “MYMACRO?” for editing. 


When a macro is open, edit it, or enter its def- 
inition with the same commands you use in a 
text buffer. After you edit the macro, press (Q] 
to close its definition and return to the 
edit mode. The first line of the macro must 
begin with a name that is not already used in 
order to close the definition and return to 
Edit. 


Saves macros on an OS-9 file. Strl specifies a 
list of macros to be saved. Separate the macro 
names with spaces. Str2 specifies the pathlist 
for the file on which you want to save the 
macros. For example: 


-Save "mymac ro'myfi le" | ENTER 


saves the macro “MYMACRO”’ on the file 
“MYFILE”. 


~save "maca macb macc"mfile" | ENTER 


saves the macros “MACA,” ‘““MACB,” and 
“MACC” on the file “MFILE”. 


Searches the text file buffer for the specified 
string. When a match is found, it stops and 
displays that line. The n option permits a 
search for the nth occurrence of a string 
match. This command is the same as § n str. 


7-29 


OS-9 Commands Reference 


-LOAD str 


-DEL str 


.DIR 


-CHANGE n 
str1 str2 
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Loads macros from an OS-9 file. As each 
macro loads, Edit verifies that no other macro 
already exists with the same name. If one 
does, the macro with the duplicate name does 
not load, and Edit skips to the next macro on 
the file. Edit displays the names of all macros 
it loads. For example, 


-load "macrofile'" | ENTER 


loads the macros in the file called 
MACROFILE. 


load “mytite” 
loads the macros in the file called MYFILE. 


Deletes the macro specified by the string. For 
example, 


.del "mymacro" 
deletes the macro called MYMACRO. 


.del “list™ 
deletes the macro called LIST. 


Displays the current edit buffer area. All edit 
buffers and macros currently in memory are 
displayed. 


Changes the occurrence of str1 to str2. The n 
option permits n occurrences of strl to be 
changed to str2. 
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Q Ends a macro edit session and returns you to 
ma the normal edit mode. For example: 


Search_and_Delete ¥N $STR 

'This example MACRO is used to 
icheck 

fihe atring at the beginning of 
'an #N number of lines. If the 
'string matches, it will delete 
'that line from the text buffer 
'file. 

I 

INOTE: The way the editor 
'processes a MACRO causes it to 
'see any parameters in the outer 
1166p TIP St... This, Then 
'parameter is processed before 
'the STR parameter. 

l 


*] I'Move to start of 


m 'edit buffer 
[ istart of outer loop 
~neob 'test for buffer end 
[ istert of inner loop 
LAST Setter ‘Lest Tor not string 
Imatch 
+ oo. to next line if 


'no match 
lif tlag clear ekip 
Inext command 


D ‘delete line af tlag 
iset 

] 'end of inner loop 

] #N fend oF otter Loep 


' End of Macro 


For practice in using macro commands, turn to Sample Session 5 
in this chapter. 


oN 
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Sample Session 1 
Clear the buffer by deleting its contents. 


You Type: D* 
Screen Shows: AD* 


Insert three lines into the buffer. Begin each line with a space, 
which is the command for inserting text. 
You Type: OMY FIRST LINE 
OMY SECOND LINE 


OMY THIRD LINE [ENTER] 
Screen Shows: MY FIRST LINE 


MY SECOND LINE 
MY THIRD LINE 


Move the edit pointer to the top of the text. The editor always 
considers the first character you type a command. 


Note: always shows * on the screen. Typing -+* also 
moves the edit pointer to the beginning of a buffer. 


You Type: 
aA 


Screen Shows: 


List (display) the first line you inserted into the buffer. 
You Type: L 


Screen Shows: L 
MY FIRST LINE 


Display the first two lines you inserted into the buffer. 
You Type: Be. 
Screen Shows: Le 
MY FIRST LINE 
MY SECOND LINE 


Move to the next line and display it. 


You Type: 

Screen Shows: MY SECOND LINE 
Move to the next line and display it. 

You Type: 

Screen Shows: MY THIRD LINE 
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Using L, display text beginning at the position of the edit 


pointer. 
You Type: L 
Screen Shows: a 


MY THIRD LINE 
Insert a line into the buffer. 


Note: In the next sample you see that the insert comes 
before the current position of the edit pointer. 


You Type: OINSERT A LINE 
Screen Shows: INSERT A LINE 


The following command line consists of more than one command. 
moves the edit pointer to the top of the text. L dis- 
plays the text, and the asterisk (+) following L indicates that text 
is displayed through to the end of the buffer. 


You Type: (CTRL }(7 JL * 
Screen Shows: AL + 


MY FIRST LONE 
MY SECOND LINE 
INSERT A LINE 
MY THIRD LINE 


Show the position of the edit pointer. 
You Type: L 


Screen Shows: L 
MY FIRST LINE 


Move the edit pointer forward two lines and display the lines. 


You Type: +2 


Screen Shows: +2 
INSERT A LINE 


Display all lines from the edit pointer to the end of the buffer. 
You Type: Ls 


Screen Shows: L* 
INSERT A LINE 
MY THIRD LINE 


Move the edit pointer to the end of the buffer. 
You Type: / 


Screen Shows: / 


Determine if the edit pointer is at the end of text. Since the 
screen shows no more lines, the edit pointer is at the end-of-text. 


You Type: L* 


Screen Shows: L* 
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Insert two more lines. 


You Type: OF IF TH LINE 
OLAST LINE 
Screen Shows: PLFTH LINE 
LAST LINE 
Move the edit pointer back one line, and display the line. 
You Type: ne 
Screen Shows: -2 
PoP TR LINE 
Move the edit pointer back two lines, and display the line. 
You Type: =3 
Screen Shows: -3 


MY SECOND LINE 


Move the edit pointer three characters to the right and display 
the remainder of the line. 


Note: You must put spaces between commands. 


You Type: $3 °L 
Screen Shows: 3 -L 
SECOND LINE 


Display the characters that precede the edit pointer on the cur- 
rent line. 


You Type: X 
Screen Shows: X 
MY 
Move the edit pointer to the end of the current line. 
You Type: +9 
Screen Shows: +g 


Determine if the edit pointer is at the end of the line. It is, since 
the screen shows no lines. 


You Type: L 


Screen Shows: L 


Display the characters that precede the edit pointer on the cur- 
rent line. 


You Type: X 


Screen Shows: X 
MY SECOND LINE 
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Move the edit pointer back to the beginning of the current line. 


You Type: -0 
Screen Shows: -g 
MY SECOND LINE 


Determine if the edit pointer is at the beginning of the line. 
Since the screen shows no lines, the pointer is at the beginning. 


You Type: X 


Screen Shows: X 


Go to the beginning of the text. 
You Type: 


Screen Shows: 


Insert a line of 14 asterisks. 


You Type: 14a 
Screen Shows: 114% 


KHHEHKKKHKEHKKHESE 


Insert an empty line. 


You Type: poe 
Screen Shows: ps 
Move to the top of the text, and display all lines in the buffer. 
You Type: (cTrL j(7}L + 
Screen Shows: a 


HHHEHHKHEKKKKKEE 


MY PABST Ne 
MY SECOND LENE 
INSERT A LINE 
MY THIRD: LINE 


PiPTRH LINE 
LAs te 
Move the edit pointer forward two lines. 
You Type: +2 
Screen Shows: +2 


MY PIkST LINE 


Extend the line with XXX. 
You Type: ee 


Screen Shows: Ee" xxxe , 
MY FIRST LINE XXX 


Display the current line. 
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Note: The previous E command moved the edit pointer to 
the next line. 
You Type: 8 
Screen Shows: L 
MY SECOND LINE 


Extend three lines with YYY. 
You Type: ES TuyYY™ 
Screen Shows: ES" yyy" 
MY SECOND LINE YY xX 
INSERT ALINE YYY 
MY THIRD LINE YY 


Move back 2 lines. 
You Type: -2 
Screen Shows: -2 
INGER LT &: LENE YY 


Move the edit pointer to the end of the line and then move the 
edit pointer back four characters. Display the current line, start- 
ing at the edit pointer. 


You Type: +9 <4 L 
Screen Shows: +9 <4 L 
ba Be 


Truncate the line at the current position of the edit pointer. This 
command removes the YYY extension. 
You Type: U 
Screen Shows: U 
INSERT A: LINE 


Go to the top of the text and display the contents of the buffer. 


You Type: L* 
Screen Shows: AL x 


KHHKKHKHHHHHHEHE 


MY FIRST LANE RAR 

MY SECOND LINE YY 
INSERT “Ay LINE 

MY THIRD LINE YY 

PLP 1 a. tN 

LAST LINE 
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Delete the current line and the next line. 


You Type: D2 
Screen Shows: D2 


KHHKEKKKEKKEKKEE 


Move the edit pointer forward two lines. 


You Type: +2 
Screen Shows: +2 
INSERT A LINE 


Delete this line. 
You Type: D 


Screen Shows: D 
INSERT A LINE 


Display the current line. 


You Type: i 
Screen Shows: L 
MY THIRD LINE YYY¥ 


Move the edit pointer to the right three characters and display 
the text. 
You Type: >3L 


Screen Shows: »93L 
THERD LINE YYY 


Kill (delete) the 11 characters that constitute THIRD LINE. 


You Type: K11 
Screen Shows: K11 
THIRD: SINE 
Go to the beginning of the line and display it. 
You Type: -9 
Screen Shows: -Q 
MY YYY 


Concatenate (combine) two lines. Move the edit pointer to the 
end of the line; delete the character at the end of the line; move 
the edit pointer back to the beginning of the lines. Display the 
line. 
You Type: +O K -O 
Screen Shows: 0K -@ 
MY YYYPLETH- EINE 


Separate the two lines by inserting an end-of-line character. 


You Type: >6 I/ / 
Screen Shows: “if 7 
ay EY 
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Note: The end of line character is inserted before the current 
position of the edit pointer. 


You Type: L | 
Screen Shows: L ww 
FIFTH LINE 


Sample Session 2 
Clear the buffer by deleting its contents. 


You Type: D* 
Insert lines. 
You Type: TONE TWO THREE 1.0 


OONE 
cOTWO 

COOTHREE 

TONE TWO THREE 2.2 
SONE 

cOTWo 

“DOTHREE 

TONE TWO THREE 3.2 


Screen Shows: ONE TWO THREE 1.9 WwW 


ONE 
TWO 
THREE 
UNG. TWO THREE. 248 
ONE 
TWO 
THREE 
ONE TWO THREE 3.98 


Go to the top of the text, and display all lines in the buffer. 

You Type: i 
Screen Shows: ad 

UNE TWO THREE 1.48 

ONE 

TWO 
THREE 
ONE TWO THREE 2.98 


ONE a 


TWO 
TASEE 
ONE TWO THREE 3.8 
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Search for the next occurrence of TWO. 
You Type: Ss. "THO" 
Screen Shows: S"TWO" 
ONE TWO THREE 1.90 


Search for all occurrences of TWO that are between the edit 
pointer and the end of the buffer. 
You Type: S*/TWO/ 
Screen Shows: S*/TWO/ 
fiNE TWG THREE 1.8 
TWO 
ORE TWO THREE. 2.22 
TWO 
ONE TWO THREE 3.9 


Go to the top of the buffer, and change the first occurrence of 
THREE to ONE. 


You Type: C/THREE/ONE/ 
Screen Shows: ® C/THREE/ONE/ 


ONE: TWO: ONE 1.8 


Move the edit pointer to the top of the buffer. Set the anchor to 
Column 2, and then use the search command to find each occur- 
rence of TWO that begins in Column 2. Skip all other 
occurrences. 


You Type: A2 S*/TWO/ 
Screen Shows: © A2 S*/TWO/ 

TWO 

TWO 


Move the edit pointer to the top of the buffer. Set the anchor to 
Column 1, and change each occurrence of ONE that begins in 
that column to XXX. 


Note: ONE in Line 1 is not changed, since it does not begin 
in Column 1. 
You Type: AC*/ONE/XXX/ (ENTER) 
Screen Shows: * AC*/ONE/XXX/ 
XXX TWO ONE 1.98 
XXX 
XXX TWO THREE 2.90 
X X X 
XXX TWO THREE 3.90 
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Go to the top of the buffer, and display the text. 
You Type: (CTRL [7 JL * 
Screen Shows: L* 

XXX TWO ONE 1.90 
X XX 
TWO 
THREE 
XXX TWO THREE 2.90 
X X X 
TWO 
THREE 
XXX TWO THREE 3.9 


Change the remaining ONE to XXX. 


Note: The anchor is no longer set. It is reset to zero after 
each command is executed. 
You Type: C/ONE/XXX/ 
Screen Shows: C/ONE/XXX/ 
XXX TWO XXX 1.8 


Move to the beginning of the current line. 


You Type: -9 


Screen Shows: -g 
XXX FUG RA 18 


Change three occurrences of XXX to ZZZ. 


You Type: C3/XXX/ZZZ7 
Screen Shows: C3/XXX7ZZ2z/ 
222. TWO: XXX T.8 
722 TW 227 4 0 
ZZ22 


Sample Session 3 


Clear the buffer by deleting its contents: 
You Type: D* 
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Display the directory of buffers and macros. The dollar sign ($) 
identifies the secondary buffer as Buffer 0. The asterisk (*) iden- 
tifies the primary buffer as Buffer 1. Edit has no macros defined. 
This is the initial environment when you start Edit. 


You Type: .DIR 

Screen Shows: .DIR 
BUFFERS: 
$ ) 
* 1 
MACROS: 


Insert some lines into Buffer 1 so that later you can identify it. 


You Type: OBUFFER ONE 1.8 
OBUFFER ONE 2.8 
UBUFFER ONE 3.8 
UBUFFER ONE 4.86 

Screen Shows: BUFFER ONE 1.@ 
BUFFER ONE 2.2 
BUFFER ONE 3.9 
BUFFER ONE 4.2 

Display the text in Buffer 1. 
You Type: L* 


Screen Shows: Al x 
BUFFER: UNE. . 142 
BUFFER GONE 2.2 
BUFFER ONE 3.8 
BUFFER ONE 4.0 


Make Buffer 0 the primary buffer. Buffer 1 becomes the second- 
ary buffer. 

You Type: Bg 

Screen Shows: Bg 
Display the directory of buffers and macros. 


Note: The symbols identifying the buffers are now reversed. 


You Type: .DIR 
Screen Shows: .DIR 


BUFFERS * 
$ 1 
* 0 


MACROS: 
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Insert some lines into Buffer 0. 


You Type: OBUFFER ZERO 1. 
LIBUF FER “ZERU 2. 
UBUFFER ZERO. 2; 
UIBUP FER ZERO 4: 
Screen Shows: BUFFER ZERO 1.98 
BUFFER ZERO 2.8 
BUFFER ZERO 3.28 
BUFFER ZERO 4.0 
Display the text in Buffer 0. 
You Type: Le 
Screen Shows: ig 
BUFFER ZERU 1. 
BUPEER ZERU 2: 
BUPFER -ZERU 3. 
BUFFER ZERO 4. 
Switch to Buffer 1. 
You Type: B 
Screen Shows: B 
Display the text in Buffer 1. 
You Type: i 
Screen Shows: AL* 
BUFFER ONE 1.9 
BUFFER ONE. 2. 2 
BUPFER UNE 3.2 
BUFFER GONE 4.9 
Move the edit pointer to Line 3 in this buffer. 
You Type: +2 
Screen Shows: +2 


BUFFER ONE 3.9 
Switch to Buffer 0. 


You Type: Bg 

Screen Shows: BO 
Display the text in Buffer 0. 

You Type: L* 

Screen Shows: L+* 


BUFFER ZERO 
BUFFER ZERO 
BUFFER. ZERO 
BUPFER ZERO 


AWD - 
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Move the edit pointer to Line 2 in this buffer. 
You Type: + 
Screen Shows: + 
BUFFER ZERO 2.90 


Switch to Buffer 1. 
You Type: B 
B 


Screen Shows: 


Display the text in Buffer 1 from the current position of the edit 
pointer. 


Note: The position of the edit pointer has not changed since 
you switched to Buffer 0. 
You Type: L+* 
Screen Shows: L+* 
BUFFER QNE 328 
BUFFER ONE. 4.9 


Switch to Buffer 0. 
You Type: BO 


Screen Shows: Ba 


Display the text in Buffer 0 from the current position of the edit 
pointer. 


Note: The position of the edit pointer has not changed since 
you switched to Buffer 1. 
You Type: L* 
Screen Shows: L* 
BUFTER ZEB 2.8 
BUPFER ZERO 3.9 
BUFFER ZERD 4.8 


Delete the contents of Buffer 0. 
You Type: D« 


Screen Shows: AD* 


BUFFER ZERU 
BUFFER ZERU 
BUFFER. ZERO 
BUFFER ZERO 


AWD > 
22a a2 


Make Buffer 1 the primary buffer and Buffer 0 the secondary 
buffer. 
You Type: B 


Screen Shows: B 


7-43 


OS-9 Commands Reference 


Move two lines from the primary buffer (Buffer 1) into the sec- 
ondary buffer (Buffer 0). 


You Type: P2 
Screen Shows: AP? 


BUFPER ONE. W.8 
BUFFER ONE €.9 


Switch to Buffer 0, and show that the lines were moved to it. 


You Type: B@(CTRL }(7)L* 
Screen Shows: BO*L* 


BUFFER. UNE Wa% 
BUFFER: ONE 24% 


Switch to Buffer 1. Go to the bottom of the buffer, and get the 
text out of the secondary buffer. 


You Type: B/G* 
Screen Shows: B/G* 
BUFFER ONE 1.8 
BUFFER ONE 2.8 


Show the contents of the buffer. 


Note: The order of the lines is changed as a result of mov- 
ing the text. 


You Type: (CTRL }(7 JL * 
Screen Shows: Als 


BUPPER -ONE: 3 
BUFFER ONE 4. 
BUFFER ONE 7. 
BUrrER ENE 2. 


NX a BQ 


Move two lines into the secondary buffer. 
You Type: P2 
Screen Shows: P2 
BUFFERK ONE 3.2 
BUFFER ONE 4..@ 


Move to the bottom of the buffer, and get the lines back out of 
the secondary buffer. 


You Type: /G* 

Screen Shows: /G* 
BUFFER ONE 3.2 
BUFFER ONE 4.9 
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Show that the order of the lines is restored. 


You Type: (CTRL {7 JL * 
Screen Shows: L* 
BUFFER ONE. 7.8 
BUFFER ONE. 2.8 
BUFFER ONE. 3.2 
BUFFER ONE 4.98 
Sample Session 4 
Clear the buffer by deleting its contents: 
You Type: (CTRL }[7 JD* 
Enter some lines of text. 
You Type: DEINE MONE 


OSECOND LINE OF TEXT (ENTER] 
OTHIRD LINE OF TEXT (ENTER) 
OFOURTH LINE 
OF IFTH LINE 


OLAST LINE 
Screen Shows: LINE ONE 


SEGUND: LINE “OF TEA T 
Tete LOWE OF Pe eT 
FOURTH LENE 


FIFTH LINE 
LAST LINE 
Open the file Oldfile for writing. 
You Type: .WRITE"oldfile' (ENTER | 
Screen Shows: JWRITE"oldfile"™ 
Write all lines to the file. 
You Type: (CTRL }[7 JW» 
Screen Shows: All x 
LINE ONE 


SECOND LAINE. GF TEXT 
THERD: LOWE. UF TEXE 
FOURTH LINE 

FIFTH CINE 

LAST Lie 


END: CF TEXT # 


Close the file. 


You Type: .WRITE// 
Screen Shows: JWRITE/S/ 
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Verify that the buffer is empty. 


You Type: (CTRL }[7 JL * 
Screen Shows: a 

Open the file Oldfile for reading. 
You Type: .READ"oldfile™ 
Screen Shows: .READ"oldfile"™ 

Create a new file called Newfile for writing. 
You Type: .WRITE"newfile"™ 
Screen Shows: .WRITE"newfile"™ 


Read four lines from the input file. The screen shows the lines as 
they are read in. 


You Type: R4 
Screen Shows: R4 
LINE ONE 


SECOND GENE OF LEX 
EAIRD LEE OP TEXT 
FOURTH LINE 


Read all the remaining text from the file. The screen shows the 
lines. When there is no more text, the screen shows the *END OF 
FILE* message. 


You Type: Re 
Screen Shows: R* 
PIFTH LINE 
LAST LINE 


*END OF FILES 


Go to the top of the buffer, and display the text to make sure it 
is inserted into the buffer. 


You Type: (CTRL )(7 JL * 
Screen Shows: AL x 
LINE ONE 


SECOND LINE OF TEXT 
THIRD CINE OF TEXT 
FOURTH LINE 

PLP TR Lae 

LAST LINE 
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Write three lines to the output file, and display the lines. 


You Type: W3 
Screen Shows: W3 
LINE ONE 


SECOND LINE. OF TEXT 
THIRD CINE OF TEXT 


Move to the next line and display it. 


You Type: + 
Screen Shows: + 
FIFTH LINE 


Show that when writing lines, the editor starts at the current 
line and not at the top of the buffer. 


You Type: W 
Screen Shows: W 
FIFTH LINE 


Go to the top of the buffer, and display the text to be sure that 
the lines were written to the output file. 


You Type: (CTRL ){7 JL * 
Screen Shows: AL + 
FOURTH LINE 
LAST LINE 
Clear the buffer. , 
You Type: (CTRL ){7JD* 
Screen Shows: AD« 
FOURTH LINE 
LAST LUNE 


Switch to Buffer 2. Open the input file Oldfile, and read two 
lines from it. 


You Type: B2 .READ"oldfile'™ R2 [ENTER] 
Screen Shows: B2 .READ"oldfile™ R2 
LINE ONE 


SECOND LINE: OF TEXT 


Switch to Buffer 1. Open the input file Oldfile and read one line 
of text. 


You Type: B .READ"oldfile™ R (ENTER | 
Screen Shows: B .READ"oldfile™ R 
LINE ONE 
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Switch to Buffer 2, and read one line. 


Note: Your place in the file was not lost. 


You Type: B2 R 


Screen Shows: B2 R 
THIRD LINE OF TEXT 


Switch to Buffer 1, and read one line of text. 


Note: Your place in the file was not lost. 


You Type: BR 


Screen Shows: BR 
SECOND LINE OF TEXT 


Switch to Buffer 2, and delete its contents. 


You Type: B2 (CTRL ){7JD+* 
Screen Shows: B2 “Dx 
LINE GNE 


SECOND IRE ti “rear 
THIRD CINE. OF TEAT 


Insert some extra lines into the buffer. 


You Type: JEXTRA LINE ONE (ENTER ] 
TEXTRA LINE TWO [ENTER] 
Screen Shows: EXTRA LINE ONE 


EXTRA LINE TWO 


Try to write B2 buffer to file. It fails because you have not 
opened a file in this buffer. 


You Type: (CTRL }(7 JW * 
Screen Shows: All» 


SPiLe SLUSED* 
Close the file for Buffer 1, and return to Buffer 2. 


You Type: B .WRITE// B2 [ENTER] 
Screen Shows: B .WRITE// B2 
Open the old “write” file for reading, and then read it back in. 
You Type: .READ"newfile™ R* 
Screen Shows: .READ"newfile™ R* 
LINE -GNE 


SECOND LINE OF “TEAT 
TRERD GING. OF PEAT 
Poe a: ohne 


*END OF FILE* 
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Display the contents of the buffer. 


a Note: It read the file into the beginning of the buffer, since 
that was the position of the edit pointer. 


You Type: (CTRL \(7 JL * 
Screen Shows: AL x 
LINE ONE 


SECOND LINE: GF TEAL. 
THIRD CINE OF TERT 
Pee. -L DNE 

EXTRA LINE ONE 
EXTRA LINE TWO 


Sample Session 5 
Delete all text from the edit buffer. 


You Type: (CTRL }{7 JD* 
Insert three lines. 
You Type: OLINE ONE 
TLINE TWO 
cy CLINE THREE 
Screen Shows: LINE ONE 
LINE TWO 
LINE TAREE 
Create a new macro using an empty string. 
You Type: .MAC// 
Screen Shows: M: 


Display the contents of the macro mode, which is now open. 


Note: The E prompt is now M. 


You Type: (CTRL J(7 JL + 
Screen Shows: Al x 


Define the macro. 


You Type: OF IND 
US" TWO" 
Screen Shows: FIND 
OD, Ss" Two" 
Display the contents of the macro. 
You Type: (CTRL }{7 JL * 
Screen Shows: gle 
FIND 
s"Two" 
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Close the macro’s definition. 


You Type: Q 
Screen Shows: E: 

Display the directory of buffers and macros. 
You Type: .DIR 
Screen Shows: <DIR 

BUPFERS? 
$ Q 
* 1 
MACROS: 
FIND 
Display the contents of the edit buffer. 
You Type: (CTRL J(7 JL + 
Screen Shows: a1 
ENE NE 
LINE TWO 
Line THREE 

Use the FIND macro to find the string TWO. 
You Type: wF UND 
Screen Shows: .F IND 

LINE TWO 

Reopen the definition of the FIND macro. 
You Type: .MAC/FIND/ 
Screen Shows: .MAC/FIND/ 

M: 

Show that the macro is still intact. 

You Type: (CTRL J(7 JL * 
Screen Shows: a 

FIND 

oT Ao" 


Add the numeric parameter and the string parameter to the 
macro’s header. 
You Type: C/FIND/FIND #N $STR/ 
Screen Shows: C/FIND/FIND #N $STR/ 
FIND: #N: $SSTR 


Move to the second line of the macro. 


You Type: + {ENTER 
Screen Shows: + 
s"Two" 
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Give the macro’s parameters to the S command. Now the FIND 
macro will perform the same function as the S command. 


You Type: C/"TWO"/ #N $STR/ 
Screen Shows: C/"TWO''/ #N $STR 
S #N $STR 
Close the macro’s definition. 
You Type: Q 
Screen Shows: E: 
Display the contents of the edit buffer. 
You Type: (CTRL (7 }L* 
Screen Shows: AL 
LINE ONE 
LINE TWO 
LINE THREE 
Use the FIND macro to find the next two occurrences of LINE. 
You Type: .FIND 2 /LINE/ (ENTER ] 
Screen Shows: .FIND 2 /LINE/ 
LiANE ONE 
LINE TWO 
Create a new macro. 
You Type: .MAC// 
Screen Shows: JMACT / 
M: 


Define the macro FIND_LINE, which performs the same func- 
tion as the S command except that it returns the edit pointer to 
the head of the line after finding the last occurrence of STR. 


You Type: OF IND LINE #N $STR 
Screen Shows: FIND_LINE #N $STR 
You Type: oS #N $STR 
Screen Shows: S #N $STR 
Turn off the verify mode. 
You Type: V6 
Screen Shows: VG 
Move the edit pointer to the first character of the current line. 
You Type: -9 
Screen Shows: -Q 
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Close the macro’s definition. 


You Type: Q 
Q 


Screen Shows: 


Ww 
ES | 
Display the contents of the edit buffer. 
You Type: (CTRL }[7 JL * | 
Screen Shows: a 
LINE QNE 
LINE TWO 
LINE TRREE 
Use the FIND_LINE macro to search for the string TWO. 
You Type: .FIND_LINE/TWO/ 
Screen Shows: .FIND_LINE/TWO/ 
LINE TWO 
Show that the FIND _LINE macro left the edit pointer at the 
head of the line. 
You Type: L 
Screen Shows: L 
LINE TWO w/ 
Create a new macro. 
You Type: .MAC// 
Screen Shows: .MAC// 
M: 
| 
\ 
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Use the exclamation point (!) command to comment itself. Type 
the following: 


[] CONVERT_TOLLINES #N 

(] ! This is a comment 

LI ! (ENTER ) 

[] ! This macro converts the next n 

[] ! space characters to new line 

[] ! characters. 

(] va 'Turn verify mode off 

U 'to prevent intermediate results 

(| ! from being displayed. 

LI ! (ENTER ) 

Ut ! Begin loop 

[] .SEARCH/ / ! Search for the space character. 

OU 1// ' Insert empty line (new line character). 

a ' Back up one line. 

Dee ae 'Delete the next space character. 

UL + 'Show line, move past it. 

‘] 1 #N 'End of loop. Repeat #N times. 

Close the macro’s definition. 
You Type: Q 
Screen Shows: Q 
a: 
Display the contents of the edit buffer. 

You Type: (cTRL }(7 JL * 

Screen Shows: a 
LINE ONE 
LINE TWO 
WING -CAREE 


Convert all space characters to new line characters. 


Note: The loop stops when the C command in the macro 
cannot find a space to delete. 


You Type: .CONVERT_TO_LINES * 
Screen Shows: .CONVERT_TO_LINES * 

LINE 

LINE 

LINE 
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Display the contents of the edit buffer. 
You Type: (CTRL [7 JL * 
Screen Shows: a 
LENE 
ONE 
LINE 
TWO 
LINE 
THREE 
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Edit Quick Reference Summary 


EDIT 


EDIT newrfile 


EDIT oldfile 


EDIT oldfile 
newfile 


OS-9 loads the editor and starts it without 
creating any read or write files. Perform text- 
file operations by opening files after the editor 
is running. 


OS-9 loads the editor and starts it. If new/file 
does not exist, Edit creates it and makes it the 
initial write file. Although this command does 
not create an initial read file, you can open 
read files after starting Edit. 


OS-9 loads the editor and starts it, making 
the initial read file oldfile. The editor creates 
a new file called SCRATCH as the initial 
write file. When the edit session is complete, 
Edit deletes oldfile and renames SCRATCH to 
oldfile. 


OS-9 loads the editor and starts it. The initial 
read file is oldfile. The editor creates a file 
called newfile as the initial write file. 


Edit Commands 


MACRO 


Executes the macro specified by the name fol- 
lowing the period (.). 


Places comments inside a macro, and ignores 
the remainder of the command line. 


Inserts a line before the current position of the 
edit pointer. 


Moves the edit pointer to the next line, and 
displays it. 


Moves the edit pointer forward n lines and dis- 
plays the line. 


Moves the edit pointer backward n lines and 
displays the line. 


Moves the edit pointer to the last character of 
the line. 
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-0 


>n 


<n 


CTRL )(7} or J for 
external 
terminals 


/ 


[commands] n 


AO 


Bn 
Cn str1 str2 
Dn 


En str 
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Moves the edit pointer to the first character of 
the current line and displays it. 


Moves the edit pointer forward n characters. 
Moves the edit pointer backward n characters. 


Moves the edit pointer to the beginning of the 
text. 


Moves the edit pointer to the end of the text. 


Repeats the sequence of commands between 
the two brackets n times. 


Skips to the end of the innermost loop or 
macro if the fail flag is not on. 


Sets the SEARCH/CHANGE anchor to Col- 
umn n, restricting searches and changes to 
those strings starting in Column n. This com- 
mand remains in effect for the current com- 
mand line. 


Returns the anchor to the normal mode of 
searching so that strings are found regardless 
of the column in which they start. 


Makes buffer n the primary buffer. 
Changes the next n occurrences of str1 to str2. 
Deletes n lines. 


Extends (adds the string to the end of) the 
next n lines. 


Gets n lines from the secondary buffer, start- 
ing from the top. Inserts the lines before the 
current position in the primary buffer. 


Inserts a line containing n copies of the string 
before the current position of the edit pointer. 


Kills n characters starting at the current 
position of the edit pointer. 


Lists (displays) the next n lines, starting at 
the current position of the edit pointer. 


Mn 


, 


Sn str 


V mode 


-CHANGE n 
strl1 str2 


-DEL str 
.DIR 
-KOB 


-LOAD str 
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Changes workspace (memory) size to n bytes. 


Puts (moves) n lines from the position of the 
edit pointer in the primary buffer to the posi- 
tion of the edit pointer in the secondary buffer. 


Quits editing (and terminates editor). If you 
specified a file(s) when you entered Edit, 
Buffer 1 is written to the output file. The 
remainder of the input file is copied to the out- 
put file. All files are closed. 


Reads n lines from the buffer’s input file. 


Searches for the next n occurrences of the 
string. 


Tabs to Column n of the present line. If n is 
greater than the line length, Edit extends the 
line with space. 


Unextends (truncates) a line at the current 
position of the edit pointer. 


Turns the verify mode on or off. 
Writes n lines to the buffer’s output file. 


Displays n lines that precede the edit position. 
The current line is counted as the first line. 


Pseudo Macros 


Changes n occurrences of str1 to str2. 


Deletes the macro specified by str. 

Displays the directory of buffers and macros. 
Tests for the end of the buffer. 

Tests for the end of the file. 

Tests for the end of the line. 


Exits the innermost loop or macro and sets the 
fail flag. 


Loads macros from the path specified in the 
string. 
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.MAC str 


.NEOB 
.NEOF 
.NEOL 
NEW 


.NSTR str 


-READ str 


S 


SEARCH n 
str 


SAVE str1 
str2 


SHELL 
command line 
SIZE 


STAR n 
STR str 


WRITE str 


-LERO n 
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Opens the macro specified by the string for 
definition. If you give an empty string, Edit 
creates a new macro. 


Tests for not end of buffer. 
Tests for not end of file. 
Tests for not end of line. 


Writes all lines up to the current line to the 
initial output file, and then attempts to read 
an equal amount of text from the initial input 
file. The text read-in is appended to the end of 
the edit buffer. 


Tests to see if string does not match the char- 
acters at the current position of the edit 
pointer. 


Opens an OS-9 text file for reading, using 
string as the pathlist. 


Exits the innermost loop or macro and suc- 
ceeds (clears the fail flag). 


Searches for n occurrences of str. 


Saves the macros specified in str1 on the file 
specified by the pathlist in sér2. 


Calls OS-9 shell to execute the command line. 


Displays the size of memory used and the 
amount of memory available in the workspace. 


Tests to see if n equals asterisk (infinity). 


Tests to see if string matches the characters at 
the current position of the edit pointer. 


Opens an OS-9 text for writing, using str as a 
pathlist. 


Tests n to see if it is zero. 


Starts at a macro loop; press (CTRL ][8). 
Ends at a macro loop; press (CTRL )(9). 


, 


yl 


Macro Text Editor / 7 


Moves edit pointer to beginning of buffer; 


press (CTRL (7). 


Editor Error Messages 


BAD MACRO 


NAME 


BAD 
NUMBER 


BAD VAR 
NAME 


BRACKET 
MISMATCH 


BREAK 


DUPL 
MACRO 


END OF 
FILE 


*FILE 
CLOSED* 


MACRO IS 
OPEN 


MISSING 
DELIM 


NOT FOUND 


You did not begin the first line in a macro 
with a legal name. You can close the definition 
of a macro after you give it a legal name. 


You have entered an illegal numeric parame- 
ter, probably a number greater than 65,535. 


You have specified an illegal variable name, 
omitted the variable name, or included a $ or 
# character in the commands parameter list. 


You have not entered brackets in pairs or the 
brackets are nested too deeply. 


You pressed or E to interrupt the edi- 
tor. After printing the error message, the edi- 
tor returns to command entry mode. 


You attempted to close a macro definition with 
an existing macro name. Rename the macro 
before trying to close its definition. 


You are at the end of the edit buffer. 


You tried to write to a file that is not open. 
Either specify a write file when starting the 
editor from OS-9, or open an output file using 
the .WRITE pseudo macro. 


You must close the macro definition before 
using the command. 


The editor could not find a matching delimiter 
to complete the string you specified. You must 
put the entire string on one line. 


The editor cannot find the specified string or 
macro. 
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UNDEFINED 
VAR 


WHAT ?? 


WORKSPACE 
FULL 
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You used a variable that is not specified in the 
macro’s definition parameter list. A variable 
parameter can be used only in the macro in 
which it is declared. 


The editor does not recognize a command. You 
typed a command that does not exist or mis- 
spelled a name. 


The buffer did not have room for the text you 
want to insert. Increase the workspace, or 
remove some text. 
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OS-9 Error Codes 


The following table shows OS-9 error codes in hexadecimal and 
decimal. Error codes other than those listed are generated by 
programming languages or user programs. 


OS-9 Error Codes 


Code 
HEX DEC Code Meaning 


$01 001 UNCONDITIONAL ABORT. An error occurred 
from which OS-9 cannot recover. All processes 
are terminated. 


$02 002 KEYBOARD ABORT. You pressed to 
terminate the current operation. 


$03 003 KEYBOARD INTERRUPT. You pressed 
either to cause the current opera- 


tion to function as a background task with no 
video display or to cause the current task to 
terminate. 


$B7 =183 ILLEGAL WINDOW TYPE. You tried to 
define a text type window for graphics or used 
illegal parameters. 


$B8 184 WINDOW ALREADY DEFINED. You tried to 
create a window that is already established. 


$B9 185 FONT NOT FOUND. You tried to use a win- 
dow font that does not exist. 


$BA 186 STACK OVERFLOW. Your process (or pro- 
cesses) requires more stack space than is 
available on the system. 


$BB = 187 ILLEGAL ARGUMENT. You have used an 
argument with a command that is 
inappropriate. 


$BD 189 ILLEGAL COORDINATES. You have given 
coordinates to a graphics command which are 
outside the screen boundaries. 
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Code 
HEX DEC 
SBE 190 
$BF 191 
$CO 192 
$C1 193 
$C2 194 
$C3 195 
$C4 196 
$C8 200 
$C9 201 
$CA 202 
$CB 203 
$CC 204 
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Code Meaning 


INTERNAL INTEGRITY CHECK. System 
modules or data are changed and no longer 
reliable. 


BUFFER SIZE IS TOO SMALL. The data you 
assigned to a buffer is larger than the buffer. 


ILLEGAL COMMAND. You have issued a 
command in a form unacceptable to OS-9. 


SCREEN OR WINDOW TABLE IS FULL. You 
do not have enough room in the system win- 
dow table to keep track of any more windows 
or screens. 


BAD/UNDEFINED BUFFER NUMBER. You 
have specified an illegal or undefined buffer 
number. 


ILLEGAL WINDOW DEFINITION. You have 
tried to give a window illegal parameters. 


WINDOW UNDEFINED. You have tried to 
access a window that you have not yet defined. 


PATH TABLE FULL. OS-9 cannot open the 
file because the system path table is full. 


ILLEGAL PATH NUMBER. The path number 
is too large, or you specified a non-existent 
path. 


INTERRUPT POLLING TABLE FULL. Your 
system cannot handle an interrupt request, 
because the polling table does not have room 
for more entries. 


ILLEGAL MODE. The specified device cannot 
perform the indicated input or output function. 


DEVICE TABLE FULL. The device table does 
not have enough room for another device. 


Code 
O HEX DEC 
$CD 205 
$CE 206 
$CF 207 
$D0 208 
$D1 209 
om 
$D2 210 
$D3 211 
$D4 212 
$D5 213 
$D6 214 
a» 
$D7 215 
$D8 216 
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Code Meaning 


ILLEGAL MODULE HEADER. OS-9 cannot 


load the specified module because its sync 
code, header parity, or cyclic redundancy code 
is incorrect. 


MODULE DIRECTORY FULL. The module 
directory does not have enough room for 
another module entry. 


MEMORY FULL. Process address space is full 
or your computer does not have sufficient mem- 
ory to perform the specified task. 


ILLEGAL SERVICE REQUEST. The current 
program has issued a system call containing 
an illegal code number. 


MODULE BUSY. Another process is already 
using a non-shareable module. 


BOUNDARY ERROR. OS-9 has received a 
memory allocation or deallocation request that 
is not on a page boundary. 


END OF FILE. A read operation has encoun- 
tered an end-of-file character and has 
terminated. 


RETURNING NON-ALLOCATED MEMORY. 
The current operation has attempted to deallo- 
cate memory not previously assigned. 


NON-EXISTING SEGMENT. The file struc- 
ture of the specified device is damaged. 


NO PERMISSION. The attributes of the speci- 
fied file or device do not permit the requested 
access. 


BAD PATH NAME. The specified pathlist con- 
tains a syntax error, for instance an illegal 
character. 


PATH NAME NOT FOUND. The system can- 
not find the specified pathlist. 
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Code 
HEX DEC 
$D9 217 
$DA 218 
$DB 219 
$DC 220 
SDD: . 221 
$DF 223 
$EO 224 
$E2 226 
$E3 227 
$EK4 228 
$E5 229 
$E6 230 
$E7 231 
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Code Meaning 


SEGMENT LIST FULL. The specified file is 
too fragmented for further expansion. 


FILE ALREADY EXISTS. The specified file- 
name already exists in the specified directory. 


ILLEGAL BLOCK ADDRESS. The file struc- 
ture of the specified device is damaged. 


PHONE HANGUP - DATA CARRIER 
DETECT LOST. The data carrier detect is lost 
on the RS-232 port. 


MODULE NOT FOUND. The system received 
a request to link a module that is not in the 
specified directory. 


SUICIDE ATTEMPT. The current operation 
has attempted to return to the memory loca- 
tion of the stack. 


ILLEGAL PROCESS NUMBER. The specified 
process does not exist. 


NO CHILDREN. The system has issued a 
wait service request but the current process 
has no dependent process to execute. 


ILLEGAL SWI CODE. The system received a 
software interrupt code that is less than 1 or 
greater than 3. 


PROCESS ABORTED. The system received a 
signal Code 2 to terminate the current 
process. 


PROCESS TABLE FULL. A fork request can- 
not execute because the process table has no 
room for more entries. 


ILLEGAL PARAMETER AREA. A fork call 
has passed incorrect high and low bounds. 


KNOWN MODULE. The specified module is 
for internal use only. 


Code 
HEX DEC 
$E8 232 
$E9 233 
$EA 234 
$EB 235 
$EC 236 
$ED 237 
$EE 238 
$EF 239 
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Code Meaning 


INCORRECT MODULE CRC. The cyclic 


redundancy code for the module being 
accessed is bad. 


SIGNAL ERROR. The receiving process has a 
previous, unprocessed signal pending. 


NON-EXISTENT MODULE. The system can- 
not locate the specified module. 


BAD NAME. The specified device, file, or mod- 
ule name is illegal. 


BAD MODULE HEADER. The specified mod- 
ule header parity is incorrect. 


RAM FULL. No free system random access 
memory is available: the system address space 
is full, or there is no physical memory avail- 
able when requested by the operating system 
in the system state. 


UNKNOWN PROCESS ID. The specified pro- 
cess ID number is incorrect. 


NO TASK NUMBER AVAILABLE. All avail- 
able task numbers are in use. 


Device Driver Errors 


I/O device drivers generate the following error codes. In most 
cases, the codes are hardware-dependent. Consult your device 
manual for more details. 


Code 
HEX DEC 
$FO 240 
$F1 241 
$F2 242 


Code Meaning 


UNIT ERROR. The specified device unit 


doesn’t exist. 


SECTOR ERROR. The specified sector number 
is out of range. 


WRITE PROTECT. The specified device is 
write-protected. 
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Code 
HEX DEC 
$F3 243 
$F4 244 
$F5 245 
$F6 246 
$F7 247 
$F8 248 
$F9 249 
$FA =250 
$FB 251 
$FC 252 
$FD 253 


Code Meaning 


CRC ERROR. A cyclic redundancy code error 
occurred on a read or write verify. 


READ ERROR. A data transfer error occurred 
during a disk read operation, or there is a 
SCF (terminal) input buffer overrun. 


WRITE ERROR. An error occurred during a 
write operation. 


NOT READY. The device specified has a not 
ready status. 


SEEK ERROR. The system attempted a seek 
operation on a non-existent sector. 


MEDIA FULL. The specified media has insuf- 
ficient free space for the operation. 


WRONG TYPE. An attempt is made to read 
incompatible media (for instance an attempt to 
read double-side disk on single-side drive). 


DEVICE BUSY. A non-shareable device is in 
use. 


DISK ID CHANGE. You changed diskettes 


when one or more files are open. 


RECORD IS LOCKED-OUT. Another process 
is accessing the requested record. 


NON-SHARABLE FILE BUSY. Another pro- 
cess is accessing the requested file. 
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Color Computer 2 Compatibility 


Color Computer 3 OS-9 Level Two provides compatibility with 
the Color Computer 2 and OS-9 Level One by letting you use the 
video display in the Alphanumeric mode (including Semigraphic 
box graphics) and in the Graphics mode. To control the display, 
it has many built-in functions that you activate using ASCII 
control characters. Any program written in a language using 
standard output statements (such as PUT in BASIC) can use 
these functions. Color Computer BASICO9 has a Graphics Inter- 
face Module that can automatically generate most of these codes 
using BASICO9 RUN statements. 


The Color Computer’s display system uses a separate memory 
area for each Display mode. Therefore, operations on the Alpha 
display do not affect the Graphics display and vice-versa. You can 
select either display with software control. (See Getting Started 
With Extended Color BASIC for more detailed information. ) 


The system interprets 8-bit characters sent to the display: 
according to their numerical values, as shown in this chart: 


Character Mode/Function 


Range 

(Hex) 

00 - OF Alpha—Cursor and screen control. 

OF - 1D Graphics—Drawing and screen control. 

1B Alpha, Graphics—Changing Palette colors. 
Alpha mode: 


1B 31 2h change cursor color 
1B 31 ch change foreground color 
1B 31 dh change background color 


where h is a hex number from 0 to 3F (0 to 
63 decimal) which determines the color. 
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Character Mode/Function 


Range 
(Hex) 
Graphics mode: 
1B 31 prh _ changes foreground/ 
background color 
where pr is a palette register # (0 - F, 
hex) 
where h is a hex number from 0 to 3F (0 
to 63 decimal) which determines the 
color. 
20-5F Alpha—Uppercase characters. 
60 - 7F Alpha—Lowercase characters. 
80 - FF Alpha—Semigraphic patterns. 


The device driver CC3I0O calls a subroutine module named 
VDGInt to handle all text and graphics for the Color Com- 
puter 2 compatibility mode. 


Color Computer 2 Compatibility / B 


Alpha Mode Display 


The Alpha mode is the standard operational mode. Use it to dis- 
play alphanumeric characters and semigraphic box graphics. Use 
it also to simulate the operation of a typical computer terminal 
with functions for scrolling, cursor positioning, clearing the 
screen, deleting lines, and so on. 


The Alpha mode assumes that each 8-bit code the system sends 
to the display is an ASCII character. If the high-order bit of the 
code is clear, the system displays the appropriate alphanumeric 
character. If the high-order bit is set, OS-9 generates a Semi- 
graphic 6 graphics box. See Getting Started With Extended Color 
BASIC for an explanation of semigraphic functions. 


The standard 32-column Alpha mode display is handled by the 
I/O subroutine module VDGInt. CC3IO calls this module 
(included in the standard boot file) to process all text and semi- 
graphic output. 


The following chart provides codes for screen display and cursor 
control. You can use the functions from the OS-9 system prompt 
by typing DISPLAY, followed by the appropriate codes. For 
instance, to clear the screen, type: 


display @c 


To position the cursor at column 16, Line 5 and display the word 
HELLO, type: 


display #2 30 25 48 45 4c 4c 4f (ENTER) 


You can also use the following codes in a language, such as 
BASICO9. To do so, use decimal numbers with the CHR$ func- 
tion, such as: 


print chr$C€@2);chr$C€48);chr$C37);chr$C€72) 
-chr$€69)3chr$C76);chr$C76);chr$C79) 
Using Alpha Mode Controls with Windows 


The control functions in the following chart also function prop- 
erly under the high resolution windowing systems. References to 
“screen” are also references to windows. 
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Alpha Mode Command Codes 


Hex Decimal 
Control Control 
Code Code Name/Function 


$01 01 HOME—Returns the cursor to the upper left 
corner of the screen. 


$02 02 CURSOR XY—Moves the cursor to character 
X of line Y. To arrive at the values for X and 
Y, add 20 hexadecimal to the location where 
you want to place the cursor. For example, to 
position the cursor at Character 5 of Line 10 
(hexadecimal A), do these calculations: 


5 
+ 20 
= 25 hexadecimal 


OA 
+ 20 
= 2A hexadecimal 


The two coordinates are $25 and $2A. 


$03 03 ERASE LINE—Erases all characters on the 
line occupied by the cursor. 


$04 04 CLEAR TO END OF LINE—Erases all 
characters from the cursor position to the 
end of the line. 
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Hex 
Control 
Code 


$05 


$06 


$07 


$08 


$09 
SOA 


$0C 


$0D 


$0E 


Decimal 
Control 
Code 


05 


06 


07 


08 


09 
10 


12 


13 


14 
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Name/Function 


CURSOR ON-OFF—Allows alteration of the 


cursor based on the value of the next 
character. Codes are as follow: 


Default 
Hex Dec Char Function Color 


$20 32 space Cursor OFF 


S21. 32 ! Cursor ON Blue 
$22 34 “Cursor ON __ Black 
$23 35 # Cursor ON 

$24 36 $ Cursor ON 

S25 3 % Cursor ON 

$26 38 & Cursor ON 

$27 39 ‘ Cursor ON 

$28 40 ( Cursor ON 

$29 41 ) Cursor ON 

$2A 42 * Cursor ON 


CURSOR RIGHT—Moves the cursor to the 
right one character position. 


BELL—Sounds a bell (beep) through monitor 
speaker. 


CURSOR LEFT—Moves the cursor to the left 
one character position. 


CURSOR UP—Moves the cursor up one line. 


CURSOR DOWN (linefeed)—Moves the 
cursor down one line. 


CLEAR SCREEN—Erases the entire screen, 
and homes the cursor (positions it at the 
upper left corner of the screen). 


RETURN—Returns the cursor to the 
leftmost character on the line. 


DISPLAY ALPHA—Switches the screen from 
Graphic mode to Alphanumeric mode. 
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Graphics Mode Display 


Use the Graphics mode to display high-resolution 2- or 4-color 
VDG graphics. The Graphics mode includes commands to set 
color, plot and erase individual points, draw and erase lines, 
position the graphics cursor, and draw circles. 


You must execute the display graphics command before using 
any other Graphics mode command. This command displays the 
graphics screen and sets a display format and color. 


The first time you enter the display graphics command, OS-9 
allocates a 6144-byte display memory. There must be at least 
that much contiguous free memory available. (You can use 
MFREE to check free memory.) The system retains the display 
memory until you give the end graphics command, even if the 
program that initiated the Graphics mode finishes. Always use 
the end graphics command to release the display memory when 
you no longer need the Graphics mode. 


Graphics mode supports two basic formats. The 2-color format 
has 256 horizontal by 192 vertical points (G6R mode). The 4- 
color format has 128 horizontal by 192 vertical points (G6C 
mode). Either mode provides both color sets. Regardless of the 
resolution of the selected format, all Graphics mode commands 
use a 256 by 192 point coordinate system. The X and Y coordi- 
nates are always positive numbers. Point 0,0 is the lower left cor- 
ner of screen. 


Many commands use an invisible graphics cursor to reduce the 
output required to generate graphics. You can explicitly set this 
cursor to any point by using the set graphics cursor command. 
You can also use any other commands that include x,y coordi- 
nates (such as set point) to move the graphics cursor to the speci- 
fied position. 


Any graphics function that draws on the graphics screen 
requires that the VDGInt module is loaded into memory during 
the system boot. 


Graphics Mode Selection Codes 


Code Format 
00 256 x 192 two-color graphics 
01 128 x 192 four-color graphics 
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Color Set and Foreground Color Selection Codes 


4-Color Format 


2-Color Format 


Ch Back- __— Fore- Back- __ Fore- 
ar 
ground ground ground ground 
00 Black Black Green Green 
Color 01 Black Green Green Yellow 
Set 0 02 Green Blue 
03 Green Red 
04 Black Black Buff Buff 
Color 05 Black Buff Buff Cyan 
Set 1 06 Buff Magenta 
07 Buff Orange 
08 Black Black 
Color 09 Black Dark Green 
Set 2 10 Black Med. Green 
ii! Black Light Green 
12 Black Black 
Color 13 Black Green 
Set 3 14 Black Red 
1d Black Buff 


Graphics Mode Control Commands 


Hex Decimal 
Control Control 
Code Code 


$0F 15 


Name/Function 


DISPLAY GRAPHICS—Switches the screen 
to the Graphics mode. Use this command 
before any other graphics commands. The 
first time you use it, the system assigns a 6- 
kilobyte display buffer for graphics. If 6K of 
contiguous memory isn’t available, OS-9 dis- 
plays an error. Follow the display graphics 
command with two characters specifying the 
Graphics mode and color/color set, 
respectively. 


PRESET SCREEN—Presets the entire 
screen to the color code passed by the next 
character. 


$10 16 
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Hex 
Control 
Code 


$11 


$12 


$13 


$14 


$15 


$16 


$17 


$18 


Decimal 
Control 
Code 


th 


18 


19 


20 


21 


22 


23 


24 


Name/Function 


SET COLOR—Sets the foreground color (and 
color set) to the color specified by the next 
character but does not change the Graphics 
mode. 


END GRAPHICS—Disables the Graphics 
mode, returns the 6K byte graphics memory 
area to OS-9 for other use, and switches to 
Alpha mode. 


ERASE GRAPHICS—Erases all points by 
setting them to the background color, and 
positions the graphics cursor at the desired 
position. 


HOME GRAPHICS CURSOR—Moves the 
graphics cursor to coordinates 0,0 (the lower 
left corner). 


SET GRAPHICS CURSOR—Moves the 
graphics cursor to the given x,y coordinates. 
For x and y, the system uses the binary 
value of the two characters that immediately 
follow. 


DRAW LINE—Draws a line in the fore- 
ground color from the graphics cursor posi- 
tion to the given x,y coordinates. For x and y, 
the system uses the binary value of the two 
characters that immediately follow. The 
graphics cursor moves to the end of the line. 


ERASE LINE—Operates the same as the 
draw line function, except that OS-9 draws 
the line in the background color, thus erasing 
the line. 


SET POINT—Sets the pixel at point x,y to 
the foreground color. For x and y, the system 
uses the binary values of the two characters 
that immediately follow. The graphics cursor 
moves to the point set. 


Hex 


Control 


Code 
$19 


S1A 


$1C 


$1D 


Decimal 
Control 
Code 


25 


26 


28 


29 
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Name/Function 


ERASE POINT—Operates the same as the 


set point function, except that OS-9 draws the 
point in the background color, thus erasing 
the point. 


DRAW CIRCLE—Draws a circle in the fore- 
ground color using the graphics cursor as the 
center point and using the the binary value 
of the next character as the radius. 


ERASE CIRCLE—Operates the same as the 
draw circle function, except that OS-9 draws 
the circle in the background color, thus eras- 
ing the circle. 


FLOOD FILL—paints with the foreground 
color, starting at the graphics cursor position 
and extending over adjacent pixels having the 
same color as the pixel under the graphics 
cursor. 


Note: When you call FILL the first time, it requests alloca- 
tion of a 512-byte stack for the fill routine. The system does 
not return this memory until you terminate graphics with 
the end graphics command. 


Note: The chart uses hexadecimal codes for compatibility 
with the OS-9 DISPLAY command. 


Display Control Codes Summary 


Ist Byte 


Dec Hex 2nd Byte 3rd Byte Function 


00 
Ol 
02 
03 


00 
O1 
02 
03 


Null 
Home alpha cursor 


Column+32 Row+32 Position alpha cursor 


Erase line 


B-9 


OS-9 Commands Reference 


Ist Byte 


Dec Hex 2nd Byte 


04 
05 
06 
07 
08 


09 
10 
Li 
12 


13 
14 
15 
16 


Ld 
18 
19 
20 


Cursor Code 


Mode 
Color Code 


Color Code 


X Coord 
X Coord 
X Coord 
X Coord 


X Coord 
Radius 
Radius 


3rd Byte 


Color Code 


Y Coord 
Y Coord 
Y Coord 
Y Coord 


Y Coord 


Function 


Erase to End of line 
Alter Cursor 

Move cursor right 
Sound terminal bell 
Move cursor left 


Move cursor up 

Move cursor down 
Erase to End of Screen 
Clear screen 


Carriage return 
Select Alpha mode 
Select Graphics mode 
Preset screen 


Select color 

Quit Graphics mode 
Erase screen 

Home Graphics cursor 


Move graphics cursor 
Draw line to x/y 
Erase line to x/y 

Set point at x/y 


Clear point at x/y 
Draw circle 
Erase circle 
Flood Fill 
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OS-9 Keyboard Codes 


Key Definitions With Hexadecimal Values 


0 30 O 30 
As Ge. ht. A 
2 32 " 22 
as goa #223 
4 34 §$ 24 
5 35 % 25 
6 36 & 26 
ia: ne 
8 38 ( 28 
9 39 } 2g 
. QA * ZA 
- 8B + 2B 
, 2G = BC 
« 22D se SD 
, 2B. & Bes 
, 2 2 “SF 


@ 40 60 

| 7C ja 61 A 41 
00 |b 62 B 42 

" TE |c 63 C 48 
00 jd 64 D 44 
00 |e 65 E 45 
00 if 66 F 46 

" BE |g 67 G 47 
[ 5B |h 68 H 48 
] 5D |i 69 I 49 
00 jj 6A J 4A 
00 |k 6B K 4B 

+ 7B il 6C £ 4c 
5F |m 6D M 4D 

} 7D |n 6E N 4E 
\ 5C !o 6F O 4F 


BREAK 
ENTER 
SPACE 


ie 2 


NUL 00 
SOH 01 
STX 02 
ETX 03 
KOT 04 
EMD 05 
ACK 06 
BEL 07 
BSP 08 
HT 09 
LF OA 
VT OB 
FF 0C 
DR OD 
CO OE 
CI OF 


Function Keys 


NORM SHFT 
05 03 
OD OD 
20 20 
08 18 
09 Lg 
OA 1A 
OC LC 


70 
71 
72 
73 
74 
75 
76 
77 
78 
19 
7A 


Need dernnrasd 


Nh gd CHMOWOV 


DLE 10 
DC1 11 
DC2 12 
DC3 13 
DC4 14 
NAK 15 
SYN 16 
ETB 17 
CAN 18 
EM 19 
SUM 1A 
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OS-9 Keyboard Control 


Functions 


Key Definitions for Special Functions and Characters 


Key 


Combination 


ALT 


(BREAK } or (CTRL JLE] 
(cTRL) (-) 
(cTRL) (, ) 
(cTRL} (- } 
(crt) (7) 


[+] or 


or 


or 


(CTRL) 


Control Function or Character 


Alternate key—Sets the high order bit on a 


character. Press char. 

Use as a control key. 

Stops the program currently executing. 
Generates an underscore (_). 
Generates a left brace ({). 

Generates a right brace (}). 


Generates a reverse slash (\). 


Generates an end-of-file (EOF). This 
sequence is the same as pressing on a 
standard terminal. 


Generates a backspace. 


Deletes the entire current line. 


Interrupts the video display of a running 
program. This sequence reactivates the 
shell and then runs the program as a back- 
ground task. 


Upper-/lowercase shift lock function. 
Generates a vertical bar (|) in reverse video. 
Generates a tilde (~) character. 

Generates an up arrow or caret (°). 
Generates a left bracket ([). 

Generates a right bracket ()). 
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Key 


Combination 


Control Function or Character 


(oTRL J(D) 


D-2 


Repeats the previous command line. 


Redisplays the command line. 


Temporarily halts output to the screen. 
Press any key to resume output. 


Enable/Disable Keyboard mouse. 
Change screens. 


Change screens in reverse order. 


Index 


ACIAPAK 5-6, 5-7, 6-96 
active state 4-2 
address 2-4 

memory 4-5 
allocate memory for devices 

6-55 

alpha mode B-3 

select B-10 
alphanumeric mode B-1 
ampersand separator 3-6 
append files 6-68 
application program 1-3 
arglist 6-2 
ASCII 2-5 

control characters B-1 

convert 6-38 
ASM _ 3-2 
asterisk, editor 7-3 
ATTR 2-10, 6-5 
attribute 2-5, 2-8, 2-10, 6-5 
auto-answer modem 6-96, 

6-108 


background 
color B-7 
process 3-7 
task 4-1 
screen 5-2 
backspace 6-93 
character 6-94, 6-106, 
6-107 
editor 7-2 
over line 6-93, 6-106 
BACKUP 5-4, 6-7 
backup a directory 6-39 
BASICO9 2-5, 2-6, 3-13, B-1 
baud rate 5-4, 5-5, 5-6, 6-96, 
6-98, 6-109 
begin a window 6-103 
bell 
character 6-95, 6-108 
sound B-10 


Dit: Zi 
stop 5-5, 5-6 
user 2-11 
bitmap 2-5 
block 
number 4-5 
devices 1-2 
bootstrap 65-1 
file 5-2 
box graphics B-3 
brackets 6-3 
buffer 3-7, 7-2 
edit 7-1 
secondary 7-1 
text 7-1 
BUILD 2-6, 3-10, 6-10, 6-71, 
6-75 
built-in commands 3-1, 3-11 
byte 2-1 


carriage return B-10 
CC3Disk 5-1 
CC3Go 5-2 
CC3IO_ 5-1, B-2 
chaining programs 6-44 
change 
attributes 2-10, 2-11 
directory 6-12, 6-91, 
6-84 
filename 6-84 
priority 3-12, 6-88 
system parameters 6-93 
character 
ASCII 2-5 
delete 6-107 
devices 1-2 
backspace 6-94, 6-106, 
6-107 
bell 6-95, 6-108 
delete line 6-94, 6-107 
dup 6-95, 6-107 
end-of-file 6-94, 6-107 
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character (cont’d) 
end-of-record 6-94, 
6-107 
lowercase B-1 
pause 6-95, 6-108 
quit 6-95, 6-108 
reprint 6-95, 6-107 
terminate 6-95, 6-108 
uppercase B-2 
CHD 3-11, 6-12 
check disk structure 6-25 
child process 3-6, 4-2 
CHX 3-11, 6-12 
circle 
draw B-9 
erase B-9, B-10 
clear 
screen B-5 
to end-of-line B-4 
clock 5-2 
cluster 2-4, 2-5 
CMDS directory 5-1, 5-3, 5-4 
CMP 6-14 
COBBLER 6-16, 6-72 
code 
alpha mode control B-4 
cursor B-5 
object 2-7 
position-independent 4-8 
re-entrant 4-6 
color 
background B-7 
foreground B-7, B-8 
select B-10 
set, graphics B-7 
combine files 6-68 
command 
grouping 3-2, 3-9 
help 6-51 
interpreter 6-90 
line 3-1, 3-2 
parameters, editor 7-3 
separator 3-1, 3-5 
summary, editor 7-55 


command codes 
alpha mode B-4 
graphics B-7 
commandname 6-2 
commands 
ASM 3-2 
ATTR 2-10, 2-11, 6-5 
BACKUP 6-7 
BUILD 2-6, 3-10, 6-10, 
6-71, 6-75 
built-in 3-11 
CHD 3-11, 6-12 
CHX 3-11, 6-12 
CMP 6-14 
COBBLER 6-16, 6-72 
CONFIG _ 5-2, 5-3, 5-4, 
6-18 
COPY 2-3, 3-6, 4-8, 6-22 
DATE 6-24 
DCHECK 6-25 
DEINIZ 6-30 
DEL 6-31 
DELDIR 2-3, 6-33 
DIR 2-6, 2-9, 6-35 
DISPLAY 6-38 
DSAVE 6-39 
DUMP 2-8, 6-72 
ECHO 6-42 
edit macro 7-28 
editor 7-2 
ERROR 5-2, 6-43 
EX 3-11, 6-44 
FORMAT 6-46 
FREE 6-49 
GET 2-6 
HELP 6-51 
i 3-11 
IDENT 3-3, 6-52 
INIZ 6-55 
KILL 3-12, 6-56 
LINK 6-58 
LIST 2-3, 2-5, 2-8, 3-4, 
6-59 
LOAD 4-7, 6-61 


commands (cont’d) 
MAKDIR 2-3, 2-11, 
6-63 
MDIR_ 6-64 
MERGE 6-68 
MFREE 6-69 
MODPATCH_ 6-70 
MONTYPE_ 6-74 
OS9YGEN _ 5-2, 5-3, 6-76 
3-12 
PROCS 3-7, 4-2, 6-80 
PUT 2-6 
PWD 6-82 
PXD 6-82 
RENAME 6-84 
RUNB_ 3-138 
SEEK 2-6 
SETIME 5-3, 6-86 
SETPR 3-12, 6-88 
SHELL 3-6, 6-90 
t 3-12 
TMODE 6-93 
TUNEPORT 6-98 
UNLINK 4-7, 4-8, 
6-100 
w 3-12 
WCREATE 6-103 
x 3-12 
XMODE_ 5-4, 5-5, 5-7, 
6-106 
comment, in a program 3-12 
compare files 6-14 
concurrent 
execution 3-5, 6-91 
mode 3-10 
process 3-9 
task 4-1 
CONFIG 5-2, 5-3, 5-4, 6-18 
control 
characters, ASCII B-1 
keys, editor 7-2 
convert to ASCII 6-38 
COPY 2-3, 3-6, 4-8, 6-22 


Index 


copy 
a directory 6-39 


diskettes 6-7 
CPU 4-1 
priority 6-88 
CRC 2-7, 6-71 
create 
a directory 6-63 
a file 6-10 
OS9Boot 6-16, 6-76 
process 3-6 
system diskette 5-3, 5-4, 
6-16, 6-18, 6-76 
current 
directory 4-4, 6-12 
processes 6-80 
cursor 
on/off B-5 
codes B-5 
control B-1, B-4 
graphics B-6, B-8 
home B-4 
move B-5, B-10 
cyclic redundancy checksum 
2-7 


data format 2-1 
data output, halt 7-3 
data 
redirect 3-4 
input/output 1-2 
passing 4-4 
process 2-1 
sending 2-1 
transfer 2-1 
DATE 6-24 
date 2-5 
set 6-86 
day 6-2 
DCHECK 6-25 
deallocate a device 6-30 
DEINIZ 6-30 
DEL 6-31 
delay, not ready 5-6 
DELDIR 2-8, 6-33 
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delete 
a character 6-107 
a directory 6-33 
aline 7-3 
a memory module 4-7, 
6-100 
files 6-31 
line character 6-94, 
6-107 
lines, editor 7-10 
descriptor 
device 1-2 
file 2-3 
detach a device 6-30 
device 
allocate memory 6-55 
block-oriented 1-2 
character 1-2 
deallocate 6-30 
descriptor 1-2, 5-1 
driver 1-2, 2-1, 5-1 
driver initialization 
6-55 
name 2-12, 2-13 
window 2-12 - 2-13 
devname 6-2 
DIR 2-6, 2-9, 6-35 
directory 2-2, 2-3 
attribute 2-8 
change 6-12, 6-91 
change name 6-84 
CMDS _ 5-1, 5-3, 5-4 
copy 6-39 
create 6-63 
current 4-4, 6-12 
delete 6-33 
list 6-35 
module 4-6 
ownership 2-8 
SYS 5-1, 5-4 
view 6-82 
working 6-12 
dirname 6-2 
disable echo 6-94, 6-107 


disk 
cluster 2-4 
file 2-3, 2-4 
VO 3-8 
initialization 6-46 
names 2-12 
ownership 2-8 
sector 2-4 
structure, check 6-25 
raw I/O 3-8 
unused sectors 6-49 
diskette 
copy 6-7 
density 2-5 
tracks 2-5 
system 2-2 
DISPLAY 6-38 
display 
a directory 6-35 
current processes 6-80 
date and time 6-24 
error message 6-43 
execution directory 6-82 
file contents 6-59 
free memory 6-69 
graphics B-7 
help 6-51 
memory module names 
6-64 
messages 6-42 
on next line 7-2 
text, editor 7-6 
unused disk sectors 6-49 
working directory 6-82 
double density 2-5 
draw 
acircle B-9 
aline B-8, B-10 
drivers, device 1-2 
DSAVE 6-39 
DUMP 2-8, 6-72 
dup character 6-95, 6-107 
duplicate 
last line 6-95 
line 6-107 


ECHO 6-42 
echo 6-92 
enable/disable 
6-107 


6-94, 


edit 
buffer 7-1 
commands, EDIT 7-5 
pointer 7-1, 7-2, 7-7 
EDIT, editor 7-5 
editor 7-1 
backspace 7-2 
command summary 
7-55 
command syntax 7-4 
commands 7-2 
control keys 7-2 
delete lines 7-10 
error messages 7-59 
getting started 7-4 
insert lines 7-10 
interrupt 7-3 
numeric parameters 7-3 
quick reference 7-55 
searching 7-13 
substituting 7-13 
terminate 7-2 
text file operations 7-18 
using the asterisk 7-3 
ellipsis 6-3 
enable echo 6-94, 6-101 
end graphics B-8 
end-of-file 
terminate 7-2 
character 6-94, 6-101 
end-of-line 
clearing B-4 
erase B-10 
end-of-record character 6-94, 
6-107 
erase 
acircle B-9, B-10 
aline B-10 
graphics B-8 
line B-4, B-8, B-9 
point B-9 


Index 


erase (cont'd) 
to end-of-line B-10 
Errmsg 5-2 
ERROR 5-2, 6-43 
error 3-12, 6-92 
message file 5-2 
messages, editor 7-59 
output 6-91 
path 3-4 
establish a directory 6-63 
EX 3-11, 6-44 
exclamation mark separator 
3-8 
execute 
a program 6-90 
permission 2-9, 2-10 
execution 
concurrent 3-5, 6-91 
modifier 3-1, 3-3 
sequential 3-5, 3-6, 6-91 


fields 2-6 

file 2-2 - 2-4 
attribute 2-8 
change name 6-84 
compare 6-14 


copy 6-22 
create 6-10 
delete 6-31 


descriptor 2-3 
descriptor sector 2-5 
display contents 6-59 
load in memory 6-61 
merge 6-68 
manager 9d-l 
OS9Boot 5-4 
ownership 2-8 
pointer 2-4 
procedure 2-6, 3-10, 
3-11 
random access 2-6 
security 2-8 
single-user 2-8 
size 2-5 
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file (cont'd) 

Startup 2-6, 5-1, 5-3, 

5-4 

text 2-5 
filename 2-3, 6-2 
fill portion of screen B-9 
flood fill B-9, B-10 
floppy disk names 2-12 
fonts 5-2 
foreground color B-7, B-8 
fork 3-7, 4-6 

request 4-3 
FORMAT 6-46 
FREE 6-49 


generate messages 6-42 
GET 2-6 
getting started, editor 7-4 
graphic window fonts 5-2 
graphics B-1 
color set B-7 
command codes B-7 
cursor B-6, B-8 
mode, select B-10 
end B-8 
erase B-8 
medium resolution B-6 
VDG B-6 
group 2-7 
grouping, commands 3-9 


halt data output 7-3 
hardware 1-2 
header 
information 6-52 
module 2-7, 3-3, 4-7 
HELP 6-51 
hex 6-2 
hexadecimal code display 
6-38 
home 
alpha cursor B-9 
cursor B-4 
hours 6-2 


I-code 3-13 
V/O 
paths 3-4 
transfers 3-8 
raw 3-8 
ID, process 4-4 
IDENT 3-3, 6-52 
images, pointer 5-2 
immortal 
process 6-91 
shell 3-11 
INIT 5-1 
initialize 
adisk 6-46 
a window 6-103 
INIZ 6-55 
input 2-1 
lines 3-12 
path 3-4 
redirect 6-91 
standard 4-4 
insert lines, editor 7-10 
interpreter, commands 6-90 
interprocess communication 
interrupt editor 7-3 
IOMAN 1-2, 1-3, 5-1 


kernel 1-1, 1-2 

keyboard 1-1 

keyword 3-1 - 3-3 

KILL 6-56 

kill 3-12 
a directory 6-33, 6-33 
files 6-31 


length 
of video page 6-94 
word 5-5, 5-6, 6-96, 

6-109 

line 
backspace 6-93, 6-106 
delete, editor 7-3 
draw B-8, B-10 
duplicate 6-95 


line (cont’d) 
duplication 6-107 
erase B-4, B-8, B-9, 
B-10 
syntax 6-1 
linefeed 6-94, 6-107 
lines, command 3-1 
LINK 6-58 
LIST 2-3, 2-5, 2-8, 3-4, 6-59 
list 
a directory 6-35 
current processes 6-80 
memory module names 
6-64 
segment 2-5 
with program files 2-8 
LOAD 4-7, 4-7, 6-61 
lock a module 6-58 
lockout 2-11 
logical sector 2-3, 2-4 
lowercase 6-93, 6-106 
characters B-2 


machine language 3-12 
macro text editor 7-1 
macros, edit 7-25 
MAKDIR_ 2-11, 2-3, 6-63 
management, memory 4-5 
manager 
pipe 1-2 
random block 1-2 
mark space 6-95, 6-108 
MDIR_ 6-64 
MDM kill 5-6, 5-7 
medium resolution graphics 
B-6 
memory 
address 4-5 
allocation 3-1 
display free 6-69 
load a file into 6-61 
management 1-1, 4-5 
size modifier 3-3 
memory modules 
lock 6-58 


Index 


memory modules (cont'd) 
unlink 6-100 
deleting 4-7 
display names 6-64 

MERGE 6-68 

messages with ECHO 6-42 

messages, error 6-43 

MFREE 6-69 

minutes 6-2 

MMU 4-5 

mode, alpha B-3 

mode 
alphanumeric B-1 
concurrent 3-10 
semigraphic B-1 

modem 1-1, 5-6, 5-7 
auto-answer 6-108 
name 2-12 

modifier 3-1 - 3-3 
execution 3-1, 3-3 
memory size 3-3 
redirection 3-5 

modname 6-2 

MODPAK 5-7 

MODPATCH 6-70, 6-71, 6-72, 

6-73 

module 1-3 
deleting memory 4-7 
directory 4-6 
header 2-7, 3-3, 4-7 
header information 6-52 
loading 4-7 
lock in memory 6-58 
primary 4-3 
program 2-7 
unlink 4-8 

month 6-2 

MONTYPE_ 6-74, 6-75 

move cursor B-4, B-5, B-10 

multiprogramming 4-1 

multitasking 1-1 


name 
device 2-12, 2-13 
modem 2-12 


aj 
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name (cont’d) 

printer 2-12 

program 3-3 

terminal 2-12 
next line, display 7-2 
not ready delay 5-6 
notations, syntax 6-1 
null count 6-94, 6-107 
number 

priority 3-12 

user 2-8, 4-4 
numeric parameters, editor 

7-3 


object code 2-7 
operating system 1-3 
opts 6-2 
OS9Boot 5-1, 5-4 
create 6-16, 6-76 
OS9Gen_ 5-2, 5-3, 6-72, 6-76 
OS9p2 5-1 
output 2-1. 
error 6-91 
path 3-4, 4-4 
redirect 3-11, 6-91 
owner 2-5, 2-8 


page length, video 6-107 
pages 3-3 
paint B-9 
parameter 3-1, 4-4 
change system 6-93 
command editor 7-3 
paramlist 6-2 
parent process 4-2 
parity 5-6, 5-7, 6-95, 6-108 
passing data 4-4 
pathlist 6-2 
paths 2-1 
VO 3-4 
output 4-4 
standard 3-4, 6-93 
patterns, semigraphic B-2 


pause 6-94 
character 6-95, 6-108 
screen 6-107 
permission 6-2 
execute 2-9, 2-10 
read 2-9, 2-10 
write 2-9, 2-10 
physical sector 2-4 
PIC 4-8 
pipe 1-2, 3-7, 
pipelines 3-7, 
PIPEMAN 5-1 
Piper 5-1 
point 
erase B-9 
set B-8, B-10 
pointer 
edit 7-1, 7-2 
editor 7-7 
file 2-4 
images 5-2 
port 1-2 
port, RS-232 5-4, 6-109 
position alpha cursor B-9 
position-independent 2-7 
code 4-8 
prepare adisk 6-46 
preset screen B-7 
previous line repeat 7-2 
primary module 4-3 
PRINTER 5-1 
printer 1-1, 1-2 
name 2-12 
test 6-98 
priority 
number 3-12 
change 6-88 
process 4-2, 4-4 
procedure file 2-6, 3-10, 3-11 
process 
background 3-7 
chaining 6-44 
child 3-6 
create 3-6 
current 6-80 


co” 


process (cont'd) 
data 2-1 
fork 3-7 
ID 4-4 
memory size 6-91 
priority 4-2, 4-4 
properties 4-4 
sibling 4-3 
state 4-2 
terminate 6-56 
time sharing 4-1 
processor time 4-1 
procID 6-2 
PROCS _ 3-7, 4-2, 6-80 
program 
application 1-3 
chaining 6-44 
comments in 3-12 
execution 6-90 
modules 2-7 
name 3-3 
size 3-3 
prompt 3-12 
prompting 6-92 
properties, process 4-4 
public 2-9, 2-10 
PUT 2-6 
PWD 6-82 
PXD 6-82 


quick reference, editor 7-55 
quit character 6-95, 6-108 


RAM 4-5 
random access 1-2 
files 2-6 
random block file manager 
1-2 
rate, baud 5-4, 5-5, 5-6, 6-96, 
6-98, 6-109 
raw /O 3-8 
RBF 5-1 
read 2-1, 2-11, 2-4 
permission 2-10, 2-9 
readers 3-8 


Index 


record 2-2, 2-6 

lockout 2-11 
redirect 

data 3-4 

input 6-91 

output 6-91 
redirection 3-1 

modifiers 3-4, 3-5 

output 3-11 

symbols 3-5 
re-entrant code 4-6 
remove 

directory 6-33 

files 6-31 

memory module 6-100 
RENAME 6-84 
repeat previous line 7-2 
reprint character 6-95, 6-107 
reserved characters 3-3 
ROOT 2-2, 2-3 
route data 3-4 
RS-282 5-1, 5-4, 6-96, 6-109 
run-time module 3-12 
RUNB_ 3-13 


SAVE 6-72 

SCF 5-1 

screen 
alpha B-5 
background 5-2 
clear B-5 
control B-1 
pause 6-94, 6-107 
preset B-7 

scroll pause 6-94, 6-107 

searching, editor 7-13 

secondary buffer 7-1 

seconds 6-2 

sector 2-4 
copy 6-7 
displayed unused 6-49 
file descriptor 2-5 
logical 2-3 
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security 
file 2-8 
permission 6-5 
SEEK 2-6 
segment list 2-5 
select 
alpha mode 
color B-10 
graphics mode 
semicolon, sequential 
execution 3-6 
semigraphic 
mode B-1 
patterns B-2 
sending data 2-1 
separator 3-1 
ampersand 3-6 
command 3-5 
exclamation mark 3-8 
sequential execution 3-5, 3-6, 
6-91 
set a window 6-103 
set a point B-8, B-10 
set priority 3-12 
SETIME 5-3, 6-86 
SETPR 6-88 
share time 4-1 
shell 1-3, 3-1—3-3, 3-8, 6-3 
SHELL 3-6, 6-90 
show 
a directory 6-35 
error message 6-43 
execution directory 6-82 
file contents 6-59 
free memory 6-69 
header information 6-52 
memory module 
names 6-64 
working directory 6-82 
sibling processes 4-3 
sign bit 2-2 
simultaneous execution 3-5 
single-user file 2-8 
SIO. 5-1 


B-10 
B-10 
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size 
file 2-5 
process memory 6-91 
program 3-3 
slash in device names 2-13 
sleeping 4-3 
software fonts 5-2 
sound bell B-10 
standard input 4-4, 6-93 
standard paths 3-4, 6-93 
start a window 6-103 
Startup 2-2, 2-6, 5-1, 5-3, 
5-4, 6-75 
state 4-2, 4-2 
Stdfonts 5-2 
Stdpats 5-2 
Stdptrs 5-2 
stop bit 5-5, 5-6 
string parameters, editor 7-4 
subdirectory 2-3 
delete 6-33 
submanager 1-2 
subshell 3-10 
substituting, editor 7-13 
summary, commands 6-3, 6-4 
Super user 6-56 
switch screen B-5 
symbols, redirection 3-5 


syntax 6-1 
SYS directory 5-1, 5-4 
system 
administrator 1-1 
date 6-86 
disk create 5-3, 5-4 
parameters 6-93 
priority 6-88 
time 6-86 


system diskette 2-2 
create 6-16, 6-18, 6-76 


task, background 4-1 
term 1-1 

TERM 5-1 
TERM-VDG_ 6-96 
TERM-WIN_ 6-109 


terminal name 2-12 
terminals 1-2 
terminate 
a character 6-95, 6-108 
a process 6-56 
the editor 7-2 
on error 6-92 
test delay loop 6-98 
text 6-2, B-2 
buffers 7-1 
display, editor 7-6 
editing 7-1 
file operations, editor 
7-18 
files 2-5 
tick 4-1, 4-2 
tickcount 6-2 
time 2-5, 6-24 
sharing, process 4-1 
CPU 4-1 
processor 4-1 
set 6-86 
timeslice 4-1, 4-2 
TMODE_ 6-93 
tracks 2-5 
transfer, /O 3-8 
transferring data 3-7 
TUNEPORT 6-98 
turn on 
cursor B-5 
echo 6-92 
prompting 6-92 
type 5-7 
ACIA 6-96, 6-108 
of window 6-103 
value 5-7 


UNLINK 4-7, 4-8, 6-100 
unused disk sectors 6-49 
update mode 2-11 
uppercase 6-93, 6-106 
characters B-2 


Index 


user 
bit 2-11 
number 2-8, 4-4 


value 6-2 
type 9-7 
variable 6-1 
VDG graphics B-6 
video 1-1 
page length 6-94, 6-107 
view 
current processes 6-80 
error messages 6-43 
working directory 6-82 


waiting state 4-3 
WCREATE 6-103 
window 5-2 
alpha mode controls B-3 
descriptor 2-12 
initialization 6-103 
type 6-103 
word length 5-5, 5-6, 6-96, 
6-109 
working directory 6-12 
write 2-1, 2-4, 2-11 
permission 2-9, 2-10 


XMODE_ 5-4, 5-5, 6-106 


year 6-2 
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Chapter 1 


Looking at the Basics 


BASICO9 is a computer language created for use with the OS-9 
operating system. Along with standard BASIC language state- 
ments and functions, it includes the most useful elements of the 
PASCAL computer language. 


In brief, BASIC09’s advantages are: 


Fast execution speed 


Full feature editing 


Modular 
programming 
functions 


Interfacing to OS-9 


Structured 
programming 


BASICO9 compiles procedure lines as 
you enter them. When you finish a 
procedure, you can compile it further. 
The result? Procedures that execute 
nearly as fast as machine language. 


The text editor features automatic line 
formatting, search, search and change, 
global search, global search and 
change, line renumbering, and much 
more. You can move in and out of the 
editor quickly and easily. 


You can write small, easy-to-under- 
stand procedures, then chain them to 
create sophisticated programs. You can 
call one procedure from another, 
regardless of whether the called proce- 
dure is in memory or on disk. 


Both you and your procedures can 
take advantage of almost any OS-9 
function from within BASIC, including 
the execution of disk management 
commands and application programs. 


You can structure procedures more 
efficiently and clearly by taking advan- 
tage of a variety of loop commands, 
optional line numbering, and 
BASIC09’s ability to call modules 
written in other computer languages. 
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Memory saving 
features 


Complex data 
structures 


Sophisticated 
graphics 


High speed, 
precision math 


Simple and fast 
debugging 


Using BASIC09 


Strings can be any length. For each 
operation, you can select the most effi- 
cient of five available data types. Com- 
piled procedures use less space. You 
can save several procedures into one 
file. 


Combine any type of data into a single 
dimensioned data structure that you 
can move, store, and assign easily and 
quickly. 


BASICO9 has three levels of graphics. 
The high resolution graphics and text 
capabilities feature more than 50 
functions. 


BASICO9 has a full range of fast and 
accurate math and transcendental 
capabilities including powers, roots, 
trigonometry, logic, and Boolean 
functions. 


BASICO9 provides superior debugging 
functions. It checks syntax as you 
enter lines. It points to the location of 
your errors and tells you what they 
are. You can stop programs, enter the 
debugger, then continue execution. 
Execution errors automatically put you 
in a debugging mode where you can 
examine values, and step and trace 
your way through faulty procedures. 


Before anything else, make a backup copy of your BASIC09/ 
CONFIG diskette. You can do this using the BACKUP command. 
If you are not familiar with BACKUP, see Chapter 3 of Getting 


Started With OS-9. 


To use BASICO9, boot your computer as described in Getting 
Started With OS-9. Replace the system diskette in Drive /D0 
with the BASICO9/CONFIG backup diskette and type: 


basic@9Q | ENTER 
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After a short pause, during which OS-9 loads BASICO9 from the 
diskette, the screen displays the copyright and a new prompt, 
like this: 


BASIC#S 
RS VERSION 01.00.91 
COPYRIGHT 1988 BY MOTOROLA INC. 
AND MICROWARE SYSTEMS CORP. 
REPRODUCED UNDER LICENSE 
TO TANDY CORP. 
ALL RIGHTS RESERVED 


Basicd9 
Ready 
Bs 


The B: indicates that your computer is in the BASICO9 command 
mode. From the command mode, you can issue instructions to 
the system executive to manipulate procedures (programs). 


Requesting More Memory 


Unless you specify otherwise, BASICO9 automatically sets aside 
8192 bytes of memory as a workspace into which you can type or 
load procedures. BASICO9 reserves approximately 1200 bytes of 
the workspace for internal use, leaving you with 6992 bytes for 
workspace. 


There are two ways to set aside more memory for BASICO9 
operations: 


@ You can reserve extra memory when you first enter 
BASICO9 by using the OS-9 memory size option. For 
instance, to reserve 18,176 bytes, enter this command to 
initialize BASICO9: 


basic#9 #18k 


@ You can also request additional memory after loading 
BASICO9. At the command prompt, B:, type: 


mem 180990 (ENTER ] 


This tells BASICO9 to set aside a total of 18,000 bytes of 
memory, if they are available. 


1-3 


BASICO09 Reference 


In both cases, because BASICO9 rounds the amount you request 
to the next multiple of 256, the actual reserved memory is 18176 
bytes. 


Note: If your system does not have enough free memory to 
reserve the amount you specify, the workspace size does not 
change. 


You can also use the MEM command to reduce memory. How- 
ever, BASICO9 does not reduce the size of the workspace if doing 
so destroys resident procedures. 


Writing Procedures 


BASICO9 is a modular programming language. Several proce- 
dures can occupy memory at the same time. Each procedure per- 
forms a particular function but can also interact with others to 
form a sophisticated program. 


To create or change procedures, enter the edit mode by typing 
either edit or at the B: prompt. From now on, 
when directing you to enter the edit mode, this manual uses the 
easier to type (E] command. 


Each time you type a procedure line and press (ENTER), the editor 
checks for common errors. This automatic checking lets you 
catch mistakes before you run the program, saving you testing 
and rewriting time. You can even let the automatic checking 
help you learn the rules of BASICO9. If you are not sure about a 
syntax, go ahead and type it the way you think is correct. If you 
guess wrong, BASICO9 shows where the error is and displays a 
message to tell what is wrong. 


BASIC09’s use of modules lets you divide large and complex proj- 
ects into smaller, easily manageable sections. Not only are the 
smaller procedures easier to write and understand, they are also 
easier to test. As well, because BASICO9 lets you call procedures 
that are outside the workspace (the computer's memory where 
you write and edit procedures), you can accumulate libraries of 
procedures to incorporate into future programs. 


You can work on a program’s procedures either individually or 
as a group. For example, to work on the procedures as a group, 
save your workspace procedures into a single disk file. When you 
subsequently load the file, BASICO9 automatically loads all of 
the procedures. 
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Modules of Other Languages 


BASICO9 can incorporate procedures from other languages, such 
as Pascal, C, or assembly language. Several users can then share 
the procedures. 


Executing Procedures 


You execute or run programs from the command mode. When 
you enter a procedure, BASICO9 compiles it. This means that the 
procedure is ready for execution as soon as you exit the edit 
mode. For instance, if you create a program named Greeting, 
you can execute it by typing from the command mode: 


run greeting ENTER 


Leaving BASIC09 


There are two ways you can exit from BASICO9: 
e At the B: prompt, type: 
bye 


@ Or, at the B: prompt, press (CTRL ][ BREAK]. 


When you use either method, the OS-9 prompt appears immedi- 
ately indicating that the operating system is waiting for a 
command. 


Note: When you exit BASICO9, you lose all procedures 
residing in the workspace. Be sure to save them on disk 
before leaving BASICO9. 


The Keyboard and BASIC09 


You can use some keys and key sequences to produce special 
characters and to accomplish special BASICO9 functions. You ini- 
tiate a key sequence by pressing one key and holding it down 
while pressing a second key. The following list summarizes your 
keyboard’s special functions: 
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ALT 


or 
(cTRL JLE 


or 


(oral }(_) 
(oTrt JC, J 
(oTrL JC. ) 


or 


(cTRL |(9} 


Produces graphic characters. Press char 
where char is a keyboard character). 


A control key that you use with other keys. 
(See below.) 


Stops the current program execution and 
returns to the B: prompt in BASICO09’s com- 
mand mode. 


Moves the cursor back one space. 


Produces an underscore character. 
Produces a left brace ({). 
Produces a right brace (+). 
Produces a tilde (~). 

Produces a backslash (\). 


Performs an ESCAPE function and sends an 
end-of-file message to a program receiving 


keyboard input. To be recognized, 
must be the first thing typed on a line. 


Stops execution of a program and causes 
BASICO09 to enter the Debug mode. 


Displays the next window. 
Displays the previous window. 


Deletes the current line. 


Activates or deactivates the shift lock function. 
Produces a vertical bar (| ). 

Produces an up arrow (4). 

Produces a left bracket ({). 

Produces a right bracket (1). 
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Redisplays the last line typed, and positions 
the cursor at the end of the line, but does not 
o™ process the line. Press to process the 


line, or edit the line by backspacing. If you 
edit, press again to display the edited 


line. 
(CTRL ](D ) Redisplays the current command line. 
Temporarily halts video output. Press the 


space bar to resume output. 


ENTER Performs a carriage return or executes the 
current command line. 
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Sample Session 


Although BASICO9 has several functions or modes, they all work 
together to make programming as simple as possible. The easiest 
way to learn how BASICO9 and its functions operate is to write 
and run a program. This chapter provides sample statements 
and instructions to help you learn how to use BASICO9. 


To create and execute a program: 

1. Load BASICO9 and enter the edit mode. 
. Type the BASIC program. 
. Enter the system mode and test the program’s execution. | 
. Debug the program. (Correct any programming errors.) 


. Save the completed program on disk. 


Oo a Ff W Wb 


. Load the program into memory and use it. 


om To begin the program, execute BASICO9. To be sure you have 
enough room in which to work, reserve a workspace of 10,000 
bytes by typing: 


basic@9 #10K 


The BASICO9 system mode prompt, B:, appears after the copy- 
right message. In the system mode, you can do such things as 
save and load procedures, change workspace size, and rename 
and delete procedures. 


Creating a Procedure 


To write procedures, you must be in the edit mode. You get there 
by typing: 


e (ENTER) 


This causes the screen prompt to change to E:, and the screen 


on displays: 


PROCEDURE Program 


Because you didn’t give a program name when you entered e, 
BASICO9 selects the name Program for you. Now, you must | 
write the code to make Program do something. | 
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Commands and Program Lines 


There are two responses you can give at the edit mode prompt. 
You can type an edit command, or you can type a program line. 
If you type a program line, you must type a space as the first 
character in the line. If you type an edit command, do not pre- 
cede it with a space. To make listings easier to read, this man- 
ual uses the symbol [| to indicate spaces before every line. It also 
uses the |] symbol in some procedure lines to indicate the correct 
number of spaces needed. Whenever you see either a space or a [J 
symbol in a procedure you are typing, press the space bar. 


To type the procedure in this chapter, begin each line at the E: 
prompt. After typing a line, check it for mistakes. If you make a 
mistake, use to move the cursor back. Correct the mistake. 
Then, type the remaining portion of the line. If there are no mis- 


takes, press [ENTER ]}. 


BASICO9 checks each line when you press [ENTER]. If you make a 
mistake in syntax or form, BASICO9 displays an error message. 
An arrow points to the place in the program line where the error 
occurred, and a message number indicates the type of error. 
Refer to Appendix A for an explanation of the error codes. 


If, after you enter a line, you find that you made a mistake, type 
d to delete the line. Then, retype the line. Later, the man- 
ual tells you how to change text in existing lines. 


The following program helps you do a bit of arithmetic. To get a 
feel for BASICO9, type and execute the program as directed. 
Remember, when you see either a space or (|, press the space bar. 


ODIM NUMBER1 ,NUMBER2: INTEGER 

UINPUT “Type Number..."";NUMBER1 

UINPUT “Type another....™";NUMBER2 
OPRINT "The sum of the numbers is... "s 
UPRINT NUMBER1 + NUMBER2 

LEND 


ww 
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Executing a Procedure 


To execute the procedure, quit the edit mode by typing g (ENTER). 
The compiler further processes your procedure, and the B: 
prompt reappears. To execute the program, type: 


run | ENTER 


Type in numbers when asked, and the procedure produces their 
sum. If you want to save the program on disk, the next chapter 
tells you how. Chapter 4 introduces several other edit mode com- 
mands to search, display, insert, and change programs lines and 
text. 
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The System Mode 


The BASICO9 command interpreter processes system commands. 
At the B: prompt, you can enter system commands in either 
upper- or lowercase letters. Some commands operate on the pro- 
cedures in the workspace. Others provide functions independent 
of any procedures. Following is a list of all system commands 
and their purposes. 


Command 


$ 
BYE or 


CHD 


CHX 
or DIR 


EDIT or E 
KILL 


LIST 
LOAD 
MEM 
PACK 


RENAME 
RUN 


SAV E 


Function 


Calls the shell command interpreter to execute 


an OS-9 command. 


Returns you to the OS-9 system or to the pro- 
gram that called BASICOY. 


Changes the current OS-9 data directory. 
Changes the current OS-9 execution directory. 


Displays the name, size, and variable storage 
requirement of each procedure in the 
workspace. 


Enters the procedure editor-compiler mode. 


Erases one or more procedures from the work- 
space. 


Displays a formatted listing of one or more 
procedures. 


Loads all procedures from a disk file into the 
workspace. 


Displays in bytes the current workspace size, 
or reserves a specified amount of memory for 
the workspace. 


Condenses (compiles) one or more procedures. 
Changes a procedure’s name. 


Causes a procedure in the workspace to 
execute. 


Writes one or more procedures to disk. 


3-1 


BASICO09 Reference 


Renaming Procedures 


BASIC09’s RENAME function is important for two reasons: 
First, it lets you load into the workspace procedures that have 
the same name. After you rename the workspace procedure you 
can load the second file. Second, if you let BASICO9 use the 
default procedure name, “Program,” you can rename the proce- 
dure before saving it to disk. By doing this, you avoid writing 
over—and destroying—an existing procedure file. 


To change the name of the procedure you created in the previous 
chapter from Program to Add, type: 


rename program add [ENTER 


Listing Procedure Names 


You can use the DIR command to see if RENAME worked prop- 
erly. DIR displays the names and sizes of all procedures in mem- 
ory. Because programmers use this command frequently, the 
system recognizes a shorthand call. Instead of typing dir [ENTER], 
you only need to press (ENTER). This displays a table of the proce- 
dures in the following format: 


Name Prec=Size Data-Size 

*add 182 32 

add1 217 42 

adde 218 42 
2198 free 


Proc-Size refers to the number of memory bytes required for the 
procedure. Data-Size refers to the number of memory bytes 
required for the procedure’s variables and data structures. The 
asterisk indicates the current procedure. System commands act 
on the current procedure unless you indicate otherwise. 


The last line of the DIR display tells you how many free bytes of 
memory remain in the BASICO9 workspace. 


Listing Procedures 


You can use the LIST command to view procedure lines. To dis- 
play the current procedure, type: 


list | ENTER 
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For example, this is the listing of a procedure named Alpha.bak: 


PROCEDURE Alpha__bak 


9000 DIM A:STRING 

9007 DIM TSINTEGER 

QOOBE 

QOOF PRINT “here iS the ‘alphedet 
backwards:" 

9032 PRINT 

9034 PUR: T=o8 TO -65. STEP <1 

004A PRINT CHRSCT): 

9051 PRL oe ees 

0057 NEXT T 

9062 PRINT 

9064 PRINT 

90966 END 


When you list a BASICO9 procedure, the system precedes each 
line with a relative storage address. The relative address of the 
first procedure line is always 0. In the previous example, the 
beginning address of the second procedure line in the workspace 
is 07 units from the beginning. The beginning address of the 
third line is OE hexadecimal (14 decimal) storage units from the 
procedure beginning. 


These I-Code addresses provide a way for the compiler to let you 
know where it finds an error when one occurs. 


Because BASICO9 compiles programs into I-Code, it must disas- 
semble them before it can display them on the screen. This 
means that the lines might not look exactly as typed. For 
instance, BASICO9 converts lowercase keywords (command 
names) to uppercase. BASICO9Y also eliminates some spaces. If 
your program uses control statements such as IF/THEN, FOR/ 
NEXT, and LOOP/ENDLOOP, the lines in these decision mak- 
ing or looping structures are indented as shown in the 
Alpha.bak example. Regardless of the appearance of your listed 
procedures, they execute correctly if you type their commands 
correctly. 
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Listing Procedures to a File 


There might be times when you want to send a formatted proce- 
dure listing, including I-Code addresses, directly to a file. You 
can do this using OS-9’s redirection symbol, >. To save the 
Alpha.bak procedure on a file named Alpha.list in the current 
data directory, type: 


Liat aipna.bar talpna. dist 


If you have several procedures in the workspace and want to list 
more than one to a disk file, separate the procedure names with 
commas, like this: 


list alpha.one,alpha.two,alpha.three >alpha.all 


In both of the preceding cases, the system creates the Alpha.list 
file and stores the specified listings in it. If you use a file name 
that already exists, BASICO9 displays the prompt: 


Rewrite?: 


If you press (Y], the system destroys the original file and over- 
writes it with the new listing. If you press (N), the LIST process 
terminates. 


If you wish to list a procedure, or group of procedures, to a file 
that is not in the current data directory, be sure to specify the 
complete pathlist, such as: 


list alpha.bak >» /d1/programs/alpha.rev [ENTER] 


Listing Procedures to a Printer 


In the same manner as you list procedures to a disk file, you can 
list one or more procedures to your printer. Make certain your 
printer is connected and turned on, then again use the redirec- 
tion symbol, but this time specify the printer device, like this: 


list alpha.bak »>/p [ENTER] 
Or: 
list alpha.one,alpha.two,alpha.three »>/p [ENTER] 
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Using a Wildcard 


Using the OS-9 wildcard, *, you can list all procedures in the 
workspace. For instance, if the procedures Alpha.one, Alpha.two, 
and Alpha.three exist, list them to the screen by typing: 


list* (ENTER] 

Send the list to a file by typing: 
list* alpha.all 

Or send the list to your printer by typing: 
list* /p 


Note: When you use the wildcard, the name of the file or 
device to receive the listing immediately follows the LIST” 
command. Do not use the redirection symbol. 


Saving Procedures 


You can save one or more procedures to disk using the SAVE 
command. Unlike LIST, SAVE does not include relative 
addresses. However, the syntaxes for the SAVE and LIST com- 
mands are identical. To save the procedure Alpha.bak to the cur- 
rent data directory, type: 


save alpha.bak alpha.bak 


If Alpha.bak is the current procedure, you can save it in a file 
named Alpha.bak by typing save [ENTER]. 


To save all of the procedures in the workspace to a file named 
All.programs in the current data directory, type: 


save* All.programs [ENTER 


As with LIST, to save one or more procedures in a file that is 
not in the current data directory, make sure you specify a com- 
plete pathlist. 


To save all the files in the workspace to a disk file with the 
same name as the current procedure, type save (ENTER ]. 


If the disk file you specify does not exist, BASICO9 creates it. If 
it does exist, the system displays the prompt: 


Rewrite?: 
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Press (Y) to write over the old file with the specified file. The old 
file is destroyed. 


Press (N] to terminate the SAVE operation. 


Loading Procedures 


To load a saved procedure back into BASIC09’s workspace, use 
the LOAD command and specify the appropriate pathlist. For 
instance, if your current directory is still the directory contain- 
ing Alpha.bak, load the procedure by typing: 


load alpha.bak 
To load Alpha.bak from the PROGRAMS directory on Drive /D1, 
type: 

load /d1/programs/alpha.rev 


You can run and edit a loaded procedure in exactly the same 
manner as you would a procedure you created. 


You can load any number of procedures into the workspace as 
long as your computer has sufficient memory. However, be care- 
ful that you do not load a procedure with the same name as a 
procedure already existing in the workspace. If you do, the new 
procedure overwrites (destroys) the original procedure. You can 
rename workspace procedures to avoid this problem. 


Deleting Procedures from the Workspace 


You can clear the workspace of one or more procedures using the 
KILL command. For instance, to remove Alpha.bak from the 
workspace, type: 


kill alpha.bak 


To remove more than one procedure from the workspace, sepa- 
rate the procedure names with commas. To delete Alpha.one and 
Alpha.two, type: 


kill alpha.one,alpha.two 


To clear the entire workspace, regardless of the number of proce- 
dures it contains, use the BASICO09 wildcard, *. Type: 


kill» (ENTER) 


| 
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Changing Directories 


You change working directories in BASICO9 and OS-9 in the 
same manner, by using the CHD and CHX commands. CHD 
changes the data directory, and CHX changes the execution 
directory. 


BASICO9 saves files in, or loads files from, the data directory, 
unless you specify differently in the command pathlist. It stores 
packed procedures in, or loads PACKed procedures from, the exe- 
cution directory, unless you specify differently in the command’s 
pathlist. 


Also, if you want to access OS-9 commands from BASICO9, the 
system first looks for the commands in memory. If they are not 
there, it looks for them in the execution directory, unless you 
specify differently. 


If your data directory is the ROOT directory, and you wish to 
change to a directory named PROGRAMS that is a subdirectory 
of the ROOT directory, type the following command from the 
command mode B: prompt 


chd programs [ENTER 


If your current execution directory is the system’s CMDS direc- 
tory, and you want to change to a CMDS directory in the sub- 
directory BASIC, type: 


chx basic/cmds | ENTER 


Whenever you change to a directory other than an immediate 
subdirectory, specify a complete pathlist. 


Executing OS-9 Commands 


BASICO9 lets you use OS-9 commands at any time from the sys- 
tem mode. To do so, precede the command with a dollar sign ($). 
For instance, to look at the current data directory, type: 


$dir | ENTER 


To view the current execution directory, type: 


$dir x [ENTER] 
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All OS-9 commands are available, and you can copy files, format 
diskettes, list files, or use any other functions from the system 
mode. The only restriction is that your computer must have 
enough free memory to handle the command you call. If you find 
that there is not enough memory, try using the MEM command 
to reduce reserved memory. Then, try the command again. 


Auto-Execute Procedures 


The BASICO9 compiler makes two passes through the procedures 
you write. When you enter the command, the compiler performs 
an initial compilation, checking for any syntax errors. When you 
leave the edit mode, the system compiles the procedure a second 
time and checks for any programming errors. With the PACK 
command, you can further compile your procedures so that they 
are smaller and execute even faster. 


PACK causes an extra compiler pass that removes names, line 
numbers, and non-executable statements. Before packing a 
procedure, be sure you save it. Unless you do so, you can- 
not make further changes to the procedure. 


Once you pack a file, you cannot list or edit the packed version. 
However, if you save the procedure to disk before packing, you 
can still list and edit the original file, then pack it again. 


When you save a packed procedure on disk, BASICO9 does not 
normally store it in the data directory. Because the procedure is 
now executable, the system stores it in the current execution 
directory. 


For instance, to convert Alpha.bak to a packed procedure in the 
execution directory, type: 


pack alpha.bak 


If you want to save a packed procedure under a different file- 
name, use the OS-9 redirection symbol: 


pack alpha.bak > backwards [ENTER] 


After packing a procedure, you can delete it from the workspace. 
If you then run it, BASICO9 automatically loads the file from 
disk and executes it. 


The following is a sequence of commands that demonstrate pack- 
ing and executing a procedure named Alpha.bak: 
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pack alpha.bak packs the procedure and stores 
it in the execution directory. 


kill alpha.bak deletes the procedure from the 
workspace. 


run alpha.bak loads the file into memory 
outside the workspace and 
executes it. 


kill alpha.bak deletes the module from 
memory 


You do not need to kill the file immediately after execution, but 
until you do, the file reduces available memory. 
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The Edit Mode 


You briefly used the BASICO9 built-in editor to create the Add 
procedure in Chapter 2. In addition to the features you learned 
there, the editor has other important functions. 


Although you can use any text editor or word processor to write 
BASICO9 procedures, the BASICO9 editor offers two handy 
features: 


e It is both string and line number oriented. You can 
search for strings of characters, and replace them, and 
you can reference text with optional line numbers. 


® It interfaces with the compiler and decompiler. This fea- 
ture lets BASICO9 check continuously for syntax errors 
and enables you to use procedures that conserve memory. 


Edit Commands 


The following is a summary of the edit commands: 


Command Function 

Moves the edit pointer to the next line. Causes 
a command to execute. 

+ number Moves the edit pointer ahead number lines. 

+* Moves the edit pointer to the last line. 

-number Moves the edit pointer back number lines. 

-* Moves the edit pointer to the first line. 

text Inserts an unnumbered text line before the 


current line. 


ntext Inserts the line numbered n in its correct 
numeric position. 

n Moves the edit pointer to the line numbered n. 

c/str1/str2/ Changes the next occurrence of str1 to str2. 
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Command Function 

c*/str1/str2/ Changes all occurrences of str1 to str2. 

d Deletes the current line. 

d* Deletes all the lines in the procedure. 

] Lists the current procedure line. 

1* Lists all the procedure lines. 

q Terminates the edit session. 

r Renumbers lines beginning at the current line 
in increments of 10. 

yr” Renumbers all lines in increments of 10. 

rn Renumbers lines beginning at Line n in 
increments of 10. 

r ni n2 Renumbers lines beginning at Line ni in 
increments of n2. 

s /string/ Searches for the first occurrence of string. 

s* /string/ Searches for all occurrences of string. 


Using the Editor 


The easiest way to understand the edit commands is to use 
them. The following sections show you the functions of BASICO9 
edit mode. 


The manual uses line numbers in the following procedure to 
acquaint you with all the functions of the editor. Remember, 
however, line numbers are not required with BASICO9. Proce- 
dures and programs without line numbers are shorter, faster, 
and easier to read. 


First, you need a procedure with which to work. Position your- 
self in the system mode. Then, type this line: 


e prose (ENTER 
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Now, type the following. (Remember, the small rectangle repre- 
sents a space.) 


01080 DIM PHRASESC38):STRING 
120 FOR T=1 TO 30 

(1130 READ PHRASESCt) 

014@ NEXT T 

0160 PRINT 

0170 FIRST=RNDC10) 

018@ SECOND=RNDC9)+11 

L198 THIRD=RNDC9)+21 

298 PRINT PHRASESCFIRST); 
218 PRINT PHRASESCSECOND): 
Li22@ PRINT PHRASESCTHIRD); 
02408 PRINT 

308 DATA “"Lovell”,"An orangell™., 

“Humans Ty's" A kisali™ 

318 DATA "A dark cloudl","A goose featherL", 

"A Popsiclell” 

328 DATA "Home cookingl","Cold pizzal", 

“Roek nn” Roiilg" 

W338 DATA “is charming Likell”,“makes me dream ofl” 
348 DATA “is as sticky asl™,"can ooze 
likel","smells like" 

U3S8@ DATA “can be as Tough to forget. asl”, “can 
hurt like" 

368 DATA “can be as cynical asl","“makes a mockery 


off" 


0378 DATA “drives me as crazy as[l" 

Usee Dale “a Sticky -bollipopa™", "a Web oT 
intrigue.” 

398 DATA "castor oil.","a chocolate bath.","a 
broken toe." 

406 DATA “honey and things.",“personal 


déTeacts". a. Wel Crepers.” 
U41@ DATA “strange happenings.’ 
purses” 


; a- pPennyless 


When you finish typing the procedure, type q to return to 
the system mode. Now you can test the program by typing 
either: 


run | ENTER 


or 


run prose ENTER 
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After trying the procedure, return to the edit mode by typing e 
[ENTER J. 


After displaying the procedure’s name, the editor displays Line 
100 preceded by an asterisk. The asterisk lets you know which 
line is the current line (or the line at which the edit pointer is 
located). 


Searching Through a Procedure 

You can examine a procedure in three ways: 
@ Press to display the procedure one line at a time. 
@ Skip through the procedure to a particular line. 
e List part or all of the procedure to the screen. 


When you use either of the first two methods, the line you select 
to display becomes your current line. When you use the third 
method, the current line does not change. 


Using [ENTER 


If you are still positioned at Line 100, but want to examine the 
first line of data, Line 300, press 12 times to move down. 


Using the Plus Sign to Move Forward 


Another method of moving to a specific line is to type a plus 
sign followed by the number of lines you need to advance to get 
there. Positioned at Line 100, you can type: 


+12 | ENTER 


Whether you press or use the plus sign, the last line dis- 
played is now your current line. 
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Accessing a Line Using the Line Number 


The third way to move to a particular line is to type the line 
number, followed by (ENTER). For instance, to jump back to Line 
100, type: 

100 


The editor displays Line 100 and makes it your current line. 


Using the Minus Sign to Move Backward 


In the same manner that you move forward in the procedure 
using the plus sign, you can move backward using the minus 
sign, or hyphen. 


Type 30@ to return to Line 300. To display Line 240 and 
make it your current line, type: 


~ (ENTER) 


To display Line 190 and make it your current line, type: 


~ 4 (ENTER } 


The Global Symbol 


The BASICO9 editor also makes use of the asterisk as a global 
symbol. For instance, following a command with an asterisk 
causes that command to affect the entire procedure. 


This feature lets you move quickly to the beginning and end of 
the procedure. To return to Line 100, the first line, type: 


~* CENTER } 


To move to the end of the procedure, past all the numbered lines, 
type: 


+ * (ENTER) 
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Using LIST 


The LIST command lets you select one or more lines for display 
on your screen. To see this, make the first line your current line, 
then type: 


1 [ENTER ) 


To list one or more lines, type the LIST command followed by the 
number of lines you want displayed. For instance, typing 15 
causes the current line and four others to appear on the 
screen, as shown in the following sequence of commands and the 
resulting display: 


~ * CENTER] 


15 (ENTER } 
PROCEDURE Prose 


198 DIM PHRASESC3S8): STRING 
128. FUR T#1 10 32 

13@READ PHRASESCT) 

148 NEXT T 

160 PRINT 


You can also use LIST with the BASICO9 global symbol, *. Typ- 
ing an asterisk after the LIST command produces a listing of 
the entire procedure. 


Deleting Lines 


Earlier, the manual showed that you can delete the current line 
by typing d (ENTER). Because this is such a simple process, be 
sure you don’t do it by accident. Removing the wrong line, or too 
many lines, is very frustrating in a complex procedure. 


You can also remove a group of lines from a procedure by typing 
d, followed by the number of lines you want to delete. This com- 
mand deletes the current line and specified following lines. 
Again, be careful. 


You can remove all of the lines in a procedure by using the 
global symbol, *. Typing d* erases all procedure text. 
However, the procedure name still resides in the workspace. To 
delete an entire procedure, including the name, use the KILL 
command from the system mode. 
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If you decide you don’t like the nouns used in the DATA lines of 
the Prose procedure, erase all of the DATA lines containing 
nouns (Lines 300-320) and replace them. To do so, make Line 
300 your current line by typing: 


300 
Then type: 


d (ENTER) 


Line 300 disappears and Line 310 takes its place as the current 
line. 


An alternate method of deleting the DATA lines uses only one 
command. To delete Lines 300 through 410, follow the DELETE 
command with the number of lines you want to remove—in this 
case, three: 


d3 (ENTER) 


Lines 300, 310, and 320 disappear. Line 330 becomes the cur- 
rent line. Move back a line to check that the deletions worked. 
The line numbers now skip from 240 to 330. 


Now, you need new nouns for the procedure. Type them in the 
same style as the old lines, such as: 


308 DATA "A Telephonel],"A tickle", 

"A OLP Ah ah Boy 

0315 DATA “Bad luckO","Moneyl","A bad bet(", 
"A lumpy bed{" 

328 DATA “A deep thoughth";“Sunlighti” 


Save a copy of your procedure to disk by exiting the editor and 
using the SAVE command. Then return to the edit mode and try 
the global delete by typing: 


d* CENTER ] 


Changing Text 


Using CHANGE tells the editor to search for existing text and 
replace it with new text. CHANGE, like DELETE, can easily 
cause unwanted results if you are not careful. 
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The CHANGE command requires that you use delimiters to sep- 
arate the command from the search text, and to separate the 
search text from the new text. You can select any of the following 
characters for a delimiter, as long as it does not appear in either 
the search text or the new text: 


eee heds Sad a ee Se rE 


Do not use the global symbol (*) for search and replace opera- 
tions. This manual uses a slash (/) as the CHANGE delimiter. 


The following steps outline the correct use of CHANGE: 


1. Position the editor either before or on the line in which 
you want to make a change. 


2. Type c (for CHANGE). Do not use a preceding space. 
3. Type a delimiter character, such as /. 


4. Type the characters to be changed, following them with 
the delimiter. 


5. Type the new text, followed by the delimiter. 
6. Press (ENTER J. 


Note: It is a good idea to turn on OS-9’s upper- and lower- 
case function before attempting change or search opera- 
tions. If you do not, you cannot tell whether the text you 
want to find is upper- or lowercase, or some combination of 
the two. If you type the wrong case, the change or search 
fails. 


In case you didn’t notice when typing the procedure, Line 410 
contains an incorrectly spelled word, pennyless. To correct this 
error, type the following: 


c/pennyless/penniless/ 


Immediately, the editor displays Line 410, with pennyless 
changed to penniless. 


Suppose you decide to change the number of sentence combina- 
tions available in Prose. The procedure now has 30 data entries. 
If you add five subjects, five verb phrases, and five objects, the 
procedure also needs other changes (for instance, the DIM state- 
ment in Line 100, the loop size in Line 120, and the RND state- 
ments in Lines 170 through 190). 
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A quick way to change the number 30 in Lines 100 and 120 is 
to use CHANGE’s global function. To change all occurrences of 
30 to 45, position the editor at Line 100, and type: 


c*/30/45/ 


Use the CHANGE and global CHANGE functions to adjust the 
RND statement values in Lines 170, 180, and 190. 


As well as making changes, you can use the CHANGE command 
to quickly delete portions of text within a line. To do this, type 
delimiters without new text, in this fashion: 


c/feather// 


This command changes the text A goose feather in Line 210 
to A goose. 


Searching for Text 


The editor’s SEARCH command, S, works in the same manner 
as the CHANGE command. However, SEARCH only requires 
you to specify a block of text to find. 


With SEARCH, you use delimiters to enclose the text to find. To 
test the function, position the editor at the beginning of text by 


typing: 
se 

Now, search for the word phrases, by typing: 
s/phrases/ 

The screen displays: 
*9000 1080 DIM phrases€38):STRING 


To find all occurrences of phrases throughout the procedure, use 
the global symbol. Type: 


s*/phrases/ [ENTER 
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Renumbering Lines 


The RENUMBER command, R, reorders all numbered lines and 
all references to numbered lines. You can give RENUMBER 
either one or two parameters. The first is the beginning line 
number. The second is the increment you want. The default 
increment is 10. 


For instance, the Prose procedure line numbers skip from Line 
100 to Line 120. You can renumber the entire procedure by mov- 
ing the editor to Line 100, and then typing: 


r 10 ENTER 


To change the numbering to increments of 5, beginning at Line 
100, type: 


r 100,5 (ENTER ] 


You can also change line numbering in portions of the procedure. 
To do this move the editor to the line where you want the new 
numbering to begin. Then, type in the new parameters. To 
renumber Line 100 as Line 200 and continue with increments of 
10, position the editor at Line 100. Then, type: 


r 200,10 (ENTER) 


If you are not positioned at the first line of a procedure, but you 
wish to renumber all lines, you can use the global symbol to do 
the job. From anywhere in the procedure, type: 


r* 100,10 (ENTER) 


This renumbers the entire procedure in increments of 10. 


Adding Lines 
There are two ways to add new lines to a procedure. You can: 


e@ Position the editor one line below the position for the new 
line. Then, type the new line and press (ENTER). When 
inserting lines without numbers, be sure to type a space 
as the first character of the line to tell the editor that 
the following text is a new procedure line. 


e Type a new line, giving it a line number that falls 
between two existing line numbers. 
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The following procedure adds more choices to the Prose program. 
It also adds a feature that lets you press for additional 
output, rather than having to rerun the procedure. Use the 
information presented in this section to help you insert the new 
lines into your program. Because you must change some lines, 
as well as add lines, the following listing includes the entire 
procedure. 


Referring to the original Prose listing, the lines to change are: 
100, 120, 170, 180, and 190. 


The lines to add are: 110, 150, 230, 250, 260, 270, 305, 325, 
312,374, 076,-420, 430. 


PROCEDURE prose2 

1886 DIM PHRASESC45):STRING 

118 DIM RESPONSE:STRING 

120 FOR T=1 TO 45 

130 READ PHRASESCt) 

148 NEXT T 

158 REPEAT 

168 PRINT 

170 FIRST=RNDC15) 

188 SECOND=RNDC14)+16 

198 THIRD=RNDC14)+31 

200 PRINT PHRASESCFIRST); 

218 PRINT PHRASESCSECOND); 

220 PRINT PHRASESCTHIRD); 

230 PRINT 

240 PRINT 

25@ PRINT “CUOLOUDU00Press ENTER for another 
Wit tLerstivas. 

26@ INPUT “CUUILU0000Or press the SPACEBAR and press 
ENTER 10 @fidwas«"JRESPONSE 

279 UNTIL RESPONSES" 

300 DATA “Lovell™,"An orangel”,“Humanityl™, 
"A kiss(i" 

395 DATA “A computerQ","A bookO","Miseryl” 
318 DATA “A dark cloudi”,"A goose featnerl”, 
"A Popsiclel]” | 

328 DATA "Home cookingi","Cold pizzal", 
“Rock mn“ Roll” 

sea DATA “Snow in Junel","A glass house” 
338 DATA “is charming likel™,"makes me dream of" 
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340 DATA "is as sticky asf","can ooze likel", 
"smells likelL" 

3508 DATA "can be as tough to forget asl", 

“can hurt likel"™ 

3608 DATA "can be as cynical asl", 

“makes a mockery ofL" 

370 DATA "drives me as crazy asl" 

372 DATA “can bother me likel","blackens my hopes 
like" 

374 DATA "can tickle me likel","can be as funny 
as(]" 

376 DATA "has the effect ofl" 

380 DATA "a sticky lollypop.","a web of 
intrigue,” 

390 DATA "castor oil.","a chocolate bath.","a 
broken toe." 

400 DATA "honey and things.","personal 
defeat.","a wet diaper.” 

410 DATA "strange happenings.","a penniless 

Stir ses" 

420 DATA “a slimy snake.","a bad habit." 

430 DATA "a bad memory chip.","a good fight.","a 
Si lby triends” 


The Next Step 


Even the best programmers make mistakes—a lot of them. 
BASICO9 provides a way to catch programming mistakes quickly 
and correct them. The next chapter tells you about BASICO9’s 
powerful debugging functions. 
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The Debug Mode 


The term debug refers to the process of finding programming 
errors and correcting them. BASIC09’s debugging features 
include symbolic debugging capabilities that let you examine 
variable values and test and manipulate procedures. 


With Debug, you can: 
@ Examine and change variables. 


@ Trace procedure execution. Debug lets you execute proce- 
dures and watch them run in slow motion. 


® Pause procedure execution. 
@® Resume procedure execution. 


@ Set procedure breakpoints that automatically switch to 
the debug mode. 


® Select the use of degrees or radians for trigonometric 
functions. 


@ Perform calculations. 


® Call OS-9 system commands. 


Entering the Debug Mode 


You enter Debug: 


@ Automatically, whenever an error occurs during the exe- 
cution of a procedure (unless you have included an ON 
ERROR GOTO statement to handle the error). 


@ Automatically, when a procedure executes a PAUSE 


statement. 
@ When you press during the execution of a 
procedure. 


You can tell when BASICO9 enters the Debug mode by the 
appearance of the D: prompt. When you see D:, followed by the 
cursor, Debug is waiting for your command. 


The following is a reference of all the Debug commands and what 
they accomplish: 
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Command 


$ 


BREAK 


CONT 


DEG/RAD 
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Function 


Calls OS-9’s command shell interpreter to run 
a program or an OS-9 command. From the 
Debug prompt, type $, followed by the name of 
the program or command you want to execute. 


Example: $list procedure_—one (ENTER 


Sets a breakpoint immediately before the spec- 
ified procedure. Use this command to re-enter 
Debug when one procedure calls another. 


If you have three procedures that call each 
other—Procl, Proc2, and Proc3—and Proc3 
does not seem to pass the correct values to 
Proc2 when it returns, set a breakpoint at 
Proc2. This causes BASICO9 to enter Debug 
before re-entering Proc2. You can then check 
your variable values. 


You can use one breakpoint for each active pro- 
cedure. Debug removes breakpoints immedi- 
ately after encountering them. 


A procedure must run before you can set a 
breakpoint in it. Use BREAK to stop execution 
when a called procedure returns to a proce- 
dure previously executed. 


Example: BREAK proc2 


Causes procedure execution to continue. 


Example: cont (ENTER 


Selects either degrees or radians as the unit of 
measurement for trigonometric functions. DEG 
and RAD affect only the current procedure. 


Examples: deg (ENTER 
rad [ENTER 


DIR 


LET 


LIST 


PRINT 


STATE 
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Displays the name, size, and variable storage 
requirements of each procedure in the work- 
space. The current working procedure has an 
asterisk before its name. All packed proce- 
dures have a dash before their names. DIR 
also shows the available memory in the 
workspace. 


If you provide a pathlist, DIR sends its data to 
the specified file. 


Example: dir (ENTER 
dir procedures | ENTER 


Terminates execution of the procedure, closes 
any open paths, and exits to the System mode. 


Example: gq 


Assigns a new value to a variable. You must 
specify variable names that are already ini- 
tialized by your program. In the Debug mode, 
you cannot use LET to copy one array to 
another array as you can in BASIC 
procedures. 


Example: let a := @ (ENTER] 
let fruit := "oranges" (ENTER] 


Displays a source listing of the suspended pro- 
cedure. The display is formatted and includes 
I-code addresses. An asterisk appears to the 
left of the last executed statement. 


Example: list 


Displays the values of variables used in the 
suspended procedure. You cannot introduce 
new variable names in the Debug mode, and 
you cannot display array structures. 


Example: print fruit 


Lists the nesting order of active procedures. 
STATE displays the highest-level procedure at 
the bottom of the calling list. The lowest-level 
procedure is the suspended procedure. 


Example: state 
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STEP 


TRON/TROFF 


Causes execution of the suspended procedure 
in specified increments. For example, typing 
STEP S executes the equivalent of the 
next five statements. If you enter STEP with- 
out an increment value, the step rate is 1. 


Using STEP with the trace function lets you 
observe the source lines as they execute. 


Because compiled I-code contains actual state- 
ment memory addresses, the top or bottom 
statements of loop structures execute only 
once. For example, in FOR/NEXT loops, FOR 
executes once, and the statement following 
FOR appears to be the top of the loop. 


Turns on or turns off the trace function. Trace 
on (TRON) causes the system to reconstruct 
the compiled code of each statement line into 
source code. Debug displays the source code 
before the statement is executed. If the state- 
ment causes the evaluation of one or more 
expressions, Debug displays each result follow- 
ing the statement. The result is preceded by 
an equal sign. 


The trace function is local to the current pro- 
cedure. If the suspended procedure calls 
another procedure, Debug suspends the trace 
function until control returns to the original 
procedure. However, once you turn on trace for 
a procedure, it continues in effect until you 
turn it off. This means that if you turn trace 
on in a called procedure, and another proce- 
dure subsequently calls it, trace continues to 
display the called procedure’s operations. 


Example: tron (ENTER 
troff | ENTER 


When Things Go Wrong 


Programming errors show up in two ways. Either your procedure 
produces incorrect results, or it terminates prematurely. 
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In the first instance, you can stop your procedure and enter 


Debug by pressing (CTRL |(C}. 


However, sometimes your program executes too quickly to allow 
you to stop it at the appropriate place. In this case, you can use 
the Edit mode to insert a PAUSE command where you wish the 
procedure to stop. PAUSE causes the procedure to halt execution 
and enter the Debug mode. 


Once in Debug, you can use the PRINT command to examine 
the procedure variables. You can use LET to manipulate the 
variable values to determine where the error or errors occur. Per- 
haps you forgot to initialize a variable or forgot to increase a loop 
counter. 


Using the Trace Function 


Sometimes, errors are more difficult to discover. If so, the next 
step is to use the trace function. To do this, type: 


tron (ENTER | 


Now press (ENTER). Each time you press [ENTER], Debug executes 
one line of the procedure. You can see the original source state- 
ment, and if an expression is evaluated, Debug prints the result 
of the expression, preceded by an equal sign. 


In this manner, you can step through the entire procedure, or 
any part of it, examining variable values as you go. 


What About Loops? 


The STEP command is helpful if you find yourself tracing the 
operation of a loop. Once you determine that the loop works cor- 
rectly, you can avoid tedious, step-by-step repetitions by turning 
trace off and using STEP to quickly run through the loop. Then, 
turn trace back on and resume single-step debugging. For 
instance, type: 


troff (ENTER | 
step 200 
tron (ENTER | 
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In Multiple Procedures 


Although the trace function is local to a procedure, you can 
pause and turn on the trace function in as many procedures as 
you wish. Trace continues to operate in each procedure until you 
turn it off using TROFF. 


To cause a procedure to halt execution when it is called by 
another procedure, use the BREAK command. 
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Data and Variables 


Data Types 


Data is information on which a computer performs its operations. 
Data is always numeric but, depending on your computer appli- 
cation, it can represent values, symbols, or alphabetic characters. 
This means that the same items of physical data can have very 
different logical meanings, depending on how a program inter- 
prets it. 


For instance, 65 can represent: 
e A numeric value to be used in a calculation. 
@ The location of a memory address. 
@ The offset of a memory location. 
@ The two character symbols 6 and 5. 


@® The character A in the ASCII table. ASCII is the abbre- 
viation for the American Standard Code for Information 
Interchange. 


Because of the differences in how BASICO9 uses data, the sys- 
tem lets you define five types of data. For instance, there are 
three ways to represent numbers. Each has its own advantages 
and disadvantages. The decision to use one way or another 
depends on the specific program you are developing. The five 
BASICO9 data types are byte, integer, real, string, and Boolean. 


In addition to the preceding data types, there are complex data 
types you can define. The manual discusses complex data struc- 
tures at the end of this chapter. 


The byte, integer, and real data types represent numbers. 


The string data type represents character data (alphabet, punc- 
tuation, numeric characters, and other symbols). The default 
length of strings is 32 characters. Using the DIM statement, you 
can specify strings of both longer and shorter lengths. 


The Boolean data type represents the logical value, TRUE or 
FALSE. 
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You can create arrays (lists) of any of these data types with one, 
two, or three dimensions. The following table shows the data 
types and their characteristics: 


Memory 

Type Allowable Values Requirements 
BYTE Whole numbers (0 to 255) One byte 
INTEGER Whole numbers (-32768 Two bytes 

to 32767) 
REAL Floating point Five bytes 

( a 1*10 at 38) 
STRING Letters, digits, One byte per 

punctuation character 
BOOLEAN True or false One byte 


Real numbers appear to be the most versatile. They have the 
greatest range and are floating point. However, arithmetic opera- 
tions involving real numbers execute much more slowly than 
those involving integer or byte values. Real numbers also take 
up considerably more memory storage space than the other two 
numeric data types. 


Arithmetic involving byte values is not appreciably faster than 
arithmetic involving integers, but byte data conserves memory. 


If you do not specify the type of variable (a symbolic name 
for a value) in a DIM statement, BASIC09 assumes the vari- 
able is real. 


The Byte Data Type 


Byte variables hold unsigned eight-bit data (integers in the 
range 0 through 255). Using byte values in computations, 
BASICO9 converts the byte values to 16-bit integer values. If you 
store an integer value that is too large for the byte range, 
BASICO9 stores only the least-significant eight bits (a value of 
255 or less), and does not return an error. 
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The Integer Data Type 


Integer variables require two bytes (16 bits) of storage. They can 
fall in the range -32768 to 32767. If a calculation involves both 
integer values and real values, BASICO9 presents the result of 
the calculation as a real number. 


You can also use hexadecimal values in integer data. To do so, 
precede the value with the dollar sign ($). For instance, to repre- 
sent the decimal value 199 as hexadecimal, type $c7. The hexa- 
decimal value range is $0000 through $FFFF. 


If you give an integer variable a value that is outside the integer 
range (greater than 32767 or less than -32768), BASICO9 does 
not produce an error. Instead it wraps around the value range. 
For instance, the calculation 32767 + 1 produces a result of 
-32768. 


This means that numeric comparisons made on values in the 
range 32768 through 65535 deal with negative numbers. You 
should limit such comparisons to tests for equality or non- 
equality. Functions such as LAND, LNOT, LOR, and LXOR use 
integer values but produce results on a non-numeric, bit-by-bit, 
basis. 


Division of an integer by another integer yields an integer. 
BASIC09 discards any remainder. 


The Real Data Type 


If you do not assign a data type to a variable, BASICO9 assumes 
the variable is real. However, programs are easier to understand 
if you define all variable types. 


BASICO9 stores as real values any constants that have decimal 
points. If a constant does not have a decimal point, BASICO9 
stores it as an integer. 


BASICO9 requires five consecutive memory bytes to store real 
numbers. The first byte is the exponent, in binary two’s comple- 
ment. The next four bytes are the binary sign and magnitude of 
the mantissa. The mantissa is in the first 31 bits; the sign of 
the mantissa is in the last (least-significant) bit of the last byte. 
The following illustration shows the memory storage of a real 
number: 
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Internal Representation of Real Numbers 


exponent mantissa 


byte: 0 f! 2 3 4 


The exponent covers the range 2.938735877x10~ °° (2-128) 
through 1.701411835x10** (2!2) as powers of 2. Operations that 
result in values out of the representation range cause an over- 


flow or underflow error. You can handle such errors using the ON 
ERROR command. 


The mantissa covers the range 0.5 through .9999999995 in steps 
of 2~-*1. This means that real numbers can represent values 
.0000000005 apart. BASICO9 rounds operation values that fall 
between these points to the nearest point. 


Because floating point arithmetic is inherently inexact, a 
sequence of operations can produce a cumulative error. Proper 
rounding, as implemented in BASICO9, reduces the effect of this 
problem, but cannot eliminate it. When using real quantities in 
comparisons, be sure your computations can produce the exact 
value you desire. 


String Variables 


A string is a variable-length sequence of ASCII values. The 
length can vary from 0, a null string, to the capacity of the 
memory available to BASICOY. 


You can define a string variable either explicitly, using the DIM 
statement, or implicitly by appending the dollar sign ($) to the 
variable identifier (variable name). For example, title$ implicitly 
identifies a string variable. 


Unless you specify otherwise, BASICO9 assigns a maximum 
string length of 32 characters. Using the DIM statement, you 
can specify a maximum length either less than or greater than 
32. To conserve memory, use DIM to assign only the maximum 
length you need for any string variable. 


The beginning of a string is always Character 1. The BASE 
statement, which sets numeric variable base numbers as either 0 
or 1, does not affect string variables. 
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If an operation results in a string too long to fit in the assigned 
maximum storage space, the system truncates the string on the 
right. It does not produce an error. 


String storage is fixed at the dimensioned length. The sequence 
of actual string byte values is terminated by the value of zero, or 
by the maximum length allotted to the string. Any unused stor- 
age after the zero byte allows the stored string to expand and 
contract within its assigned length. 


The following example shows the internal storage of a variable 
dimensioned as string [61] and assigned the value “SAM”. 
Note that Byte 4 contains the string terminator 00. The string 
does not use bytes following 00. 


stat mu{ol | 
byte: if 2 3 4 5 6 


If you assign the value “ROBERT” to the variable, BASICO9 does 
not need to terminate the string with 00 because the string is 


full: 
LR Blel{rR{t. 
byte: i Z 3 4 5 6 


The way BASICO9 handles string storage is important when you 
write programs. If you do not specify a length for strings you 
define, the system uses the default length 32. As you can see, 
this wastes computer memory if you store strings of only four or 
five characters. 


The Boolean Type 


A Boolean operation always returns either the character string 
“TRUE” or “FALSE”. You cannot use the Boolean data type for 
numeric computation—only for comparison logic. 


Do not confuse the Boolean operations AND, OR, XOR, and NOT 
(which operate on the Boolean values TRUE and FALSE) with 
the logical functions LAND, LOR, LXOR, and LNOT (which use 
integer values to produce numeric results on a bit-by-bit basis). 
An attempt to store a non-Boolean value in a Boolean variable, 
causes an error. 
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Automatic Type Conversion 


When an operation mixes numeric data types (byte, integer, or 
real values), BASICO9 automatically and temporarily converts 
the values to the type necessary to retain accuracy. This conver- 
sion lets you use numeric quantities of mixed types in most 
calculations. 


The system returns a type-mismatch error when an expression 
includes types that cannot legally mix. These errors are reported 
by the second compiler pass, which occurs automatically when 
you exit the edit mode. 


Because type conversion takes additional execution time, you can 
speed calculations by using values of a single type. 


Constants 


Constants are values in a program that do not change. They can 
use any of the five data types. The following are examples of con- 
stants in a procedure: 


HOME$=""Fort Worth" 
VALUE$=""$25 , 008 
VALUE#=25 

PAYMENT #99.99 
ANSWER=""TRUE" 
MEMORY=$@CFF 

PRINT “tne ina” 


Numeric constants are either integers or real numbers. If a 
numeric constant includes a decimal point or uses the “E format” 
exponential form, it causes BASICO9 to store the number in the 
real format, even if it could store the number in integer or byte 
format. 


You can use this feature to force a real format. For instance, to 
make the number 12 a real number, type it as 12.0. You might 
want to force real values in this way when all other values in an 
expression are real so that BASICO9 does not have to do a time- 
consuming type conversion at run time. 
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BASICO9 also stores as real numbers any numbers that do not 
have decimal points but that are too large to store as integers. 
Here are some examples of legal real constants: 


1.0 9.8433218 -.O1 
-999.000099 100000000 0644.34532 
1.95E +12 -99999.9E-33 


BASICO9 treats numbers that do not have a decimal point and 
are in the range -32768 through +32767 as integers. You must 
always precede hexadecimal numbers with a dollar sign. 


Following are examples of legal integer constants: 


12 -3000 D5 
$20 $SFF $09 
0 -12 -32768 


String Constants 


A string constant consists of a sequence of characters enclosed in 
double quotation marks, such as: 


“The End™ 


To place a string constant in a string type variable, use the 
equal symbol in this manner: 


TITLES = "Masters Of Magic" 


To include double quotation marks within a string, use two sets 
of double quotation marks, like this: 


"An ""older man" is wiser." 


A string can contain characters that have ASCII values in the 
range 0 through 255. 


Variables 


In BASICO9, a variable is local to the procedure in which it is 
defined. A variable defined in one procedure has no meaning in 
another procedure unless you use the RUN and PARAM state- 
ments to pass the variable when you call the other procedure. 


The local nature of variables lets you use the same variable 
name in more than one procedure and, unless you specify other- 
wise, have the variables operate independently of each other. 
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You can assign variables using either the LET statement with 
the assign symbol (=), or by using the assign symbol alone. For 
instance, both the following command lines are legal: 


LET PAYMENT#=44.58 
PAYMENT =44.58 


When you call a procedure, BASICO9 allocates storage for the 
procedure’s variables. It is not possible to force a variable to 
occupy an absolute address in memory. When you exit a proce- 
dure, the system returns the storage allotted for variables, and 
you lose the stored values. 


If you write a procedure to call itself (a recursive procedure), the 
call creates separate storage space for variables. 


Note: Unlike other BASICS, BASICO9 does not automati- 
cally initialize variables by setting them to zero. When you 
execute a procedure, all variables, arrays, and structures 
have random values. Your procedure must initialize the 
variables you specify to the values you require. 


Passing Variables 


When one procedure passes variable values to another procedure, 
BASICO9 refers to the passed variables as parameters. You can 
pass variables either by reference or by value. 


BASICO9 does not protect variables passed by reference. There- 
fore, the called procedure can change the values and return the 
new values. BASICO9 does protect variables passed by value, so, 
the called program cannot change them. 


To pass a parameter by reference, enclose the name of the vari- 
able in parentheses as part of the RUN statement in this 
manner: 


RUN RANDOMC16) passes the value 10 to a procedure 
called Random 


The system evaluates the storage address of each passed vari- 
able, and sends the variable to the called procedure. The called 
procedure associates the storage addresses with the names in its 
local PARAM statement. It then uses the storage area as though 
it had created it locally. This means it can change the value of 
the parameter before returning it to the calling procedure. 
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To pass parameters by value, write the value to be passed as an 
expression. BASICO9 evaluates the expression at the time of the 
call. To use a variable in an expression without changing its 
value, use null constants, such as 0 for a number or "" for a 
string, in this manner: 


RUN ADDCOLUMNCx+9) passes the value of x by 
value 

RUN TRANSLATECwS$+"""") passes the contents of w$ by 
value 


To pass parameters by value, BASICO9 creates a temporary vari- 
able. It places the result of the expression in the temporary vari- 
able and sends the address to the called procedure. This means 
that the value given to the called procedure is a copy of the 
result of the expression, and the called procedure cannot change 
the original value. 


The results of expressions containing numeric constants are 
either integer or real values; there are no byte constants. To 
send byte-type variables to a procedure, pass the values by refer- 
ence. Therefore, if a RUN statement evaluates an integer as a 
parameter and sends it to a byte-type variable, the byte variable 
uses only the high-order byte of the two-byte integer. 


Arrays 


An array is a group of related data values stored consecutively 
in memory. The system knows the entire group by a variable 
name. Each data value is an element. You use a subscript to refer 
to any element of the array. For example, an array named Graf 
might contain five elements referred to as: 


GRAF C1) GRAF C2) GRAF C3) GRAF C4) GRAF C5) 


You can use each of these elements to store a different value, 
such as: 


GRAFC1) = 25 
GRAFC2) = 47 
ORAF CS) = 39 
GRAF C4) = 16 
GRAFCS) = 58 
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Note: Normally, array elements start with 1 in BASICO9. 
However, you can use the BASE command to cause array 
elements to begin at 0. 


The previous example illustrates a single-dimensioned array. The 
elements are arranged in one row and only one subscript is used 
for each element. 


The following procedure lets you type values for a GRAF array, 
and displays the results in a simple graph. 


PROCEDURE GRAF 

UDIM GRAFC5):REAL 

(SHELL “DISPLAY @c"™ 

FOR T=1 TO 5S 

UPRINST “Value for tem #"% Ts “is 
INPUT GRAF Ct) 

LINEXT T 

PRINT 

LIPRINT 

PRINT “This is how your graph. stacks up...” 
LIPRINT 

UPOR T=7+ Ta §& 

UPRIANT “Diem #™s Ts “is 

LIFOR U=1 TO GRAFCT) 

PRINT CHRSC€79): 

UNEXT U 

LIPRINT 

AD, te, ae 

UPRINT 

HEND 


This program uses a single dimension array—in effect, a list. 


You can also create arrays with more than one dimension — 
more than one element for each row. You might use a two-dimen- 
sioned array in a program to store names and addresses. Instead 
of creating separate arrays for the name, address, and zip code, 
you could set up one array with two dimensions. 
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The following program, used to enter the names of a company’s 
employees, shows how this might be done. See the second line for 
the DIM syntax. When you run the procedure, it asks you for a 
name, address, and zip code for each of 10 employees. After you 
type the information for all the entries, the procedure displays 
the information on the screen. 


PROCEDURE Names 

UDIM NAMEC1@,3):STRING 

SHELL. -“DISPEAY 8c" 

LIBASE @ 

UFOR T=@ TO 9 

LIPRINT “Type Employes Name Now"; Ty "es * 5 
UINPUT NAMECT,@) 

UIPSINT “Type Employee Address No. "s Ty "ae 7 
LDINPUT NAMECT,1) 

UPRINT “Type Employee Zip Code Now's Ts s 
INPUT NAMECT.,2) 

UNEXT T 

SHELL: “DISPLAY @C™ 

OPRINT “And the names are..." 

LIPRINT 

LIFOR T=@ TO 9 

HRRIST NAMECT, O22 “Us NAMECE st 3s" -NAMECT «223 
UNE) 

LIEND 


The DIM statement reserves space in memory for a string array 
named Name, with two dimensions. As you enter data, the Name 
field is stored in Name(@,0), Name(1,0), Name(€2,0), and so on. 
The Address field is stored in Name(€@,1), Name(1,1), 
Name(2,1), and so on. The Zip field is stored in Name(@,2), 
Name(1,2), Name€2,2), and so on. This continues until you fill 
the grid, 10 entries with three items each. 


You can also create arrays with three dimensions. The following 
program adds one more dimension that keeps track of each 
employee’s company. It dimensions Name$ as Name$(2,10,3). 
The first dimension contains either 0 or 1 to indicate to which 
company the employee belongs. 
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PROCEDURE names2 


UDIM NAME$C€2,18,3):STRING 
SHELL "DISPLAY ec” 

UBASE @ 

UFOR X=@ TO 1 

UPRINT 

LIPRINT 

UFOR T=8 TO 9 

UPRINT 


IF X=@ THEN 
UPRINT "Type a Wiggleworth Company employee 
name..." 


hs og 3 


UJENDIF 

PRINT “Tyne: Name Nee > 14.7% <3 
HINPUT NAME$CX,T,0) 

UPRINT “Tyee. Address New™s Te. sO 
OINPUT NAME$CX,T,1) 

PRIM. “Tyee 2ip Code Now's: 14° 04.93 
DINPUT NAME$CX,T,2) 

ONEXT T 

OINEXT xX 

MSHELL. “DISPLAY #@Cc”™ 

OPRINT "The Wiggleworth employees are..." 
LUPRINT 


a | 


Ux=0@ 

UFOR T=@ TO 9 

DPRINT NAMESCX,7T,8)s “Os NAMESCX,T,193 “U"s 
NAME$CX,T,2) 

UNEXT T 

UPRINT 


— 


OPRINT “The Putforth Company employees are...” 
UPRINT 

LIX = 1 

FOR T=2@ 70 2 

OPRINT NAMES$CX,T,9); “UO; NAMESCX,T,193; “O's; 
NAME$CX,T,2) 

BNEXT Tf 


END 
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The easiest way to understand three dimensional arrays is to 
consider the first dimension as a page. In other words, if the first 
dimension in the string is 0, the employee is on the Wiggleworth 
Company’s page. If the first dimension in the string is 1, the 
employee is on the Putforth Company’s page. 


Complex Data Types 


In addition to the five standard data types, you can create your 
own data types. Using the TYPE command, you can define a 
new data type as a vector (a single-dimensioned array) of any 
previously defined type. 


For example, in the previous program, the Name variable can 
contain only one type of data, the string type. However, using 
the TYPE command you can create a variable that accepts sev- 
eral data types. 


Suppose you create an employee list procedure that uses the fol- 
lowing variables, of the following size and types: 


Name Length Contents Type 
Name 25 employee name string 
Street 20 street address string 
City 10 city of address string 
Zip — address zip code integer 
Sex — false = male, true = female Boolean 
Age — employee age byte 


You can combine all these variables into one complex data type. 
To do so, dimension the variables within a TYPE command line, 
like this: 


TYPE EMPEDYEE=NAMESSI RING 2S)]¢ SIREETESPR ING LEY I 5 
CLIYSSIRINGIIOI2 Z2ZIPSREALS SEATBORVLEAR? AGESEYTE 


This creates a new BASICO9 type, called Employee. Employee 
requires its variables to have six fields of the name, size, and 
type shown in the previous chart. 


Once you create the new data type, you can define variables to 
use it. For instance, the following program line defines Worker as 
type employee, with 10 elements in the array: 


UDIM WORKERC10):EMPLOYEE 
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To put the employee data type to work, collect your data with 
INPUT commands. Then, store the data into the new Worker 
array. The following program demonstrates how you might do 


this: 


PROCEDURE worker 
UREM 


Dimension variables for 


input 


UDIM 
UDIM 
UDIM 
UDIM 
UDIM 
UDIM 
UREM 


type 


NMS STRINGL 25 1 
SIs STRINGC2O) 
CTY:STRING((9@) 
ZPsREAL 
SX:BOQLEAN 
AG: BYTE 
Create new type and array using new 


UTYPE EMPLOYEE=NAME:STRING[25]; 
CITYEStRINGLITS J ZEPSREALS 
UDIM WORKERC1@):EMPLOYEE 


SEX: BOOLEAN; 


DIREETTSTRINGL eC 13 
AGE: BYTE 


UREM 

UFOR T= 
LLENPUT 
UINPUT 
UINPUT 


1 TO 10 
"“Name:l"',NM 
“Street <i", ST 
MOLEC ely 


INPUT 
LDINPUT 
UDINPUT 
UREM 
field names 
UWORKERCT).NAME=NM 
OWORKERCT).STREET=ST 
UWORKERCTI.CITY=CTY 
UWORKERCT).ZIP=ZP 
UWORKERCT).SEX=SX 


UWORKERCT).AGE=AG 


TEES per 
“Sex ei". Sox 
"Ages", AG 

store input 


UPRINT WORKERCT).NAME 
UPRINT WORKERCT).STREET 
UPRINT WORKERCT).CITY 
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LIPRINT 

UNEXT T 

ISHELL “DISPLAY €o0Co" 

PRINT “Fhe Vanes 29 your Files 1e@. ares. 
PRINT 

Per T=1 Th TO 


in the Worker array using 


Ww 
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UPRINT WORKERCT).ZIP 
DIF WORKERCT).SEX=TRUE 
OTHEN PRINT "Female" 


ELSE 

UPRINT "Male" 

UENDIF 

UPRINT WORKERCT).AGE 
UPRINT 


OPRINT "* * * * * © * & & & & & % & &# & & & & NM 
UPRINT 
(NEXT | 


Note that the Sex field is defined as Boolean. This means that 
you can respond only in two ways, TRUE or FALSE. The method 
of input requires only one byte of storage. To use this data you 
need to handle it so TRUE and FALSE indicate female and male. 


Complex data types can contain more than one field. Each field 
can be of any data type. You reference the fields of a complex 
data type by typing the variable name, its array index, a period 
(.), and the field name. The following lines, from the Worker pro- 
cedure, show how BASICO9 stores the data from the input lines 
into the Worker variable: 


WORKERCT).NAME=NM 
WORKERCT).STREET=ST 
WORKERCT).CITY=CTY 
WORKERCT).ZIP=ZP 
WORKERCT).SEX=SX 
WORKERCT).AGE=AG 


These lines store the values in the variables NM, ST, CTY, ZP, 
SX, and AG into the NAME, STREET, CITY, ZIP, SEX, and 
AGE fields of the Worker variable. This operation is within a 
FOR/NEXT loop that uses T as a counter. In the procedure, T 
can refer to a value in the range 1 to 10. 


The procedure uses the same type of operation to extract the 
data from the complex data type variable: 
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PRINT WORKERCT).NAME 

PRINT WORKERCT).STREET 

PRINT WORKERCT).CITY 

PRINT WORKERCT).2ZIP 

[IF WORKERCT2.5EX=TRUE. THEN PRINT “Female” 
ELSE PRINT “Male 

ENDIF 

PRINT WORKERCT).AGE 


Using the same methods, you can create complex data types that 
combine other complex data types and standard data types. 


The elements of a complex structure can be copied to another 
similar structure. Using a single assignment operator, you can 
write an entire structure to, or read an entire structure from, 
mass storage as a single entity. For example: 


PUT #2, WORKERCT) 


Because the system defines the elements of complex-type storage 
during compilation, it need not do so during runtime. This 
means that BASICO9 can reference complex structure faster than 
it can reference arrays. 
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Expressions, Operators, and 
Functions 


Manipulating Data 


BASICO9 uses expressions to manipulate data. (Expressions are 
pieces of data connected by operators.) 


An operator is a symbol or a word that signifies some action to 
be performed on the specified data. Each data item is a value. 


Expressions 


When an expression is evaluated, the result is a value of some 
data type (real, integer, string, byte, or Boolean). 


An expression might look like this: 


First First Second Second 
cry Value Operator Value Operator’ Result 
6 + 5 = al 


or like this: 


First First Second Second 
Value Operator Value Operator Result 


“Seaside” “Villa” Seaside 
Villa 


When BASICO9 evaluates an expression, it copies each value onto 
an expression stack. Functions and operators take their input 
values from this stack and return their results to it. Many 
expressions result in assignments, as do the examples shown. 
The BASICO9 makes the resulting assignment only after it com- 
putes the entire expression. This lets you use the variable that is 
being modified as one of the values in the expression, such as in 


© | this example: 
X=X+1 
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The result of an expression is always one of the five BASICO9 
data types. However, you can often mix data types within an 
expression and, in some cases, the result of an expression is of a 
different data type than any of the values in the expression. 
Such is the case if you use the less-than symbol (<), in this 
manner: 


24 < 108 


The less-than operator compares two integer values. The result 
of the comparison is Boolean; in this case, the value is TRUE. 


Type Conversion 


Because BASICO9 performs automatic type conversion of values, 
you can mix any of the three numeric data types in an expres- 
sion. When you mix numeric data types, the result is always of 
the same type as the value having the largest representation, in 
this order: real < integer < byte. 


You can use any numeric type in an expression that produces a 
real number. If you want an expression to produce a byte or inte- 
ger type value, the result must be small enough to fit the 
desired type. 


Operators 


BASICO9 has operators to deal with all types of data. Each oper- 
ator, except NOT and negation (unary -), takes two values or 
operands, and performs an operation to produce a result. NOT 
can accept only one value. The following table lists the operators 
available and the types of data they accept and produce. 


Because the same operators function on the three types of 
numeric data (byte, integer, and real), these types are referred to 
by the operand type “numeric.” 
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Operator 


“or ** 


“x 
/ 


<> or >< 


< 


<= or =< 


> 


Operand Result 

Function Type Type 
Negation numeric numeric 
Exponentiation numeric numeric 
Multiplication numeric numeric 
Division numeric numeric 
Addition numeric numeric 
Subtraction numeric numeric 
Logical Negation Boolean Boolean 
Logical AND Boolean Boolean 
Logical OR Boolean Boolean 
Logical Exclusive OR Boolean Boolean 

Concatenation string string 
Equal to all types Boolean 
Not equal to all types Boolean 
Less than numeric, stringt Boolean 


numeric, stringt Boolean 
numeric, stringt Boolean 


Less than or equal 
Greater than 


= or => Greater than or equal numeric, stringt Boolean 


+ When comparing strings, BASICO9 uses the ASCII values of 
characters as the basis for comparison. Therefore, 0 < 1,9 < A, 
A < B, A < b, b < z, and so on. 


Arithmetic Operators 


Arithmetic operators perform operations on numeric data. There- 
fore, both operands in the expression must be numeric. The fol- 
lowing table lists the arithmetic operators. 


Negation The single dash negates a number’s sign: 
-10 is negative 10. 

Exponentiation Use a caret (*) or two asterisks (**) to raise 
a number to a power: 23 is 8 (2 x 2 x 2). 
Similarly, 2**3 is 8. 

Multiplication A single asterisk causes multiplication: 
2*3 is 6. 

Division A slash causes division: 6 / 2 is 3. 
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Addition The plus sign causes addition: 3 + 3 is 6. 


Subtraction A dash causes subtraction: 6 - 3 is 2. 


Hierarchy of Operators 


BASICO9 uses the standard hierarchy of operations when calcu- 
lating expressions with multiple operators. This means that 
BASICO9 has an order in which it performs calculations involv- 
ing more than one operator. 


The following BASICO9 operators are listed in order of 
precedence: 


NOT  -— (negate) 
“ *KK 


3 / 

- ss 

— a — ae a 
AND 

OR XOR 


Also, BASICO9: 


e Performs operations enclosed in parentheses before oper- 
ations not in parentheses. 


e Performs the leftmost operations first when two or more 
operations are of equal precedence. 


You can use parentheses to override this standard precedence. 
For example: 


but 
C2. > > eS 2 


The following examples show BASICO9 expressions on the left, 
and the way BASICO9 evaluates them on the right. You can 
enter the expressions in either form, but the decompiler gener- 
ates the simpler form, shown on the left. 
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BASIC09 Equivalent 
Representation Form 
Cy a=b+cx**2/d a=b+ ((c**2)/d) 
a=b>c AND d>e OR a=((b>c) AND (d>e)) 
c=e OR (c=e) 
a=(b+c+d)/e a=((b+c)+d)/e 
a=bx«cx*d/e | a = (b**(c**d))/e 
a= -(b)**2 a = (-b)**2 
a=b=c a=(b=c) 


Relational Operators 


Relational operators make logical comparisons of any type of data 

and return a result of either TRUE or FALSE. An explanation of 

the relational operators follows. All relational operators have 
a equal precedence. 


=: Equal. Returns TRUE if both operands are 
equal, or FALSE if they are not equal. 


< Less than: Returns TRUE if the first operand is 
less than the second, or FALSE if is not. 
> Greater than: Returns TRUE if the first operand 


is greater than the second, or FALSE if it is not. 


<> or >< Unequal: Returns TRUE if the operands are not 
equal or FALSE if they are. 


<= or =< Less than or equal to: Returns TRUE if the first 
operand is less than or equal to the second 
operand. Otherwise, the operation returns 
FALSE. 


>= or => _— Greater than or equal to: Returns TRUE if the 
first operand is greater than or equal to the 
-_ second. Otherwise, the operation returns FALSE. 
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You normally use relational operators in IF/THEN statements. 
For example, if your procedure has two numeric variables, Pay- 
ments and Income, you might include command lines like this: 


IF PAYMENTS >» INCOME THEN 
PRINT "You’re Broke!" 
ENDIF 


When you combine arithmetic and relational operators in the 
same expression, BASICO9 evaluates the arithmetic operations 
first. For example: 


IF X*Y/2 <= 14 THEN 
PRINT “Average score 19 °°%. A*7¢2 
ENDIF 


BASICO9 performs the arithmetic operation x*y/2, then compares 
the result with the value 14. 


When you use relational operators with strings, BASICO9 com- 
pares the strings character by character. When it finds two char- 
acters that do not match, it checks to see which character has 
the lower ASCII code value. The string containing the character 
with the lower value comes first. 


Consider this example: 
PRINT Shunt’ 2° ""hune” 


BASICO9 compares each character in each string. Because the 
first three characters are the same, the result of the operation is 
based on the comparison of t and g. Because t (ASCII value = 
116) is “greater than” g (ASCII value = 103), the command 
prints TRUE. 


String Operators 


The string operator is the plus sign (+). This symbol appends 
one string to another. All operands must be strings, and the 
resulting value is one string. Examine, for example, the follow- 
ing line, which appends three strings: 


PRIA “ty Tr hends are "+ "Jeet and " #°"vilten 


It prints: My friends are Jack and Jill. 
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Logical Operators 


The logical, or Boolean, operators make logical comparisons of 
Boolean values. The following table describes the results yielded 
by each logical operator given the specified TRUE/FALSE values: 


Meaning of First Second 
Operator Operation Operand Operand' Result 
NOT The result is the opposite of TRUE FALSE 
the operand. FALSE TRUE 
AND When both values are TRUE, TRUE TRUE TRUE 
the result is TRUE. TRUE FALSE FALSE 
Otherwise, the result is FALSE TRUE FALSE 
FALSE. FALSE FALSE FALSE 
OR When both values are TRUE TRUE TRUE 


FALSE, the result is FALSE. TRUE FALSE TRUE 
Otherwise, the result is FALSE TRUE TRUE 


TRUE. FALSE FALSE FALSE 
XOR When only one of the values TRUE TRUE FALSE 
is TRUE, the result is TRUE FALSE TRUE 
TRUE. Otherwise the result FALSE TRUE TRUE 
is FALSE. FALSE FALSE FALSE 


Use logical operators in IF/THEN statements such as: 


IF PAYMENTS < INCOME AND INCOME+SAVINGS »> 
PAYMENTS THEN 

PRINT "You’ll have to use your savings to get 
out of this mess." 
ENDIF 


Functions 


Functions are operation sequences the system performs on data. 
In a statement, BASICO9 performs functions first. Chapter 11, 
“Command Reference,” describes the following functions. 
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Functions returning results of type real 


SIN 

COS 
TAN 
ASN 
ACS 
ATN 


LOG 


LOG10 
EXP 


FLOAT 


INT 


PI 
SQR 
SQRT 


RND 


Calculates the trigonometric sine of a number. 
Calculates the trigonometric cosine of a number. 
Calculates the trigonometric tangent of a number. 
Calculates the trigonometric arcsine of a number. 
Calculates the trigonometric arccosine of a number. 


Calculates the trigonometric arctangent of a 
number. 


Calculates the natural logarithm (base e) of a 
number. 


Calculates the logarithm (base 10) of a number. 


Calculates e (2.71828183) raised to the specified 
positive power. 


Converts byte or integer type numbers to real 
numbers. 


Calculates the largest whole number less than or 
equal to the specified number. 


Represents the constant 3.14159265. 
Calculates the square root of a positive number. 


Calculates the square root of a positive number. Its 
function is identical to SQR. 


Returns a random number. 
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Functions returning results of any numeric type 


The resulting type depends on the input type. 


ABS 
SGN 


SQ 
VAL 


Calculates the absolute value of a number. 


Returns a value to indicate the sign of the specified 
number (-1 if the number is less than 0, 0 if the 
number is 0, or 1 if the number is greater than 0). 


Calculates the square of a number. 


Converts a string to a numeric value. 


Functions returning results of type integer or type byte 


FIX 


MOD 


ADDR 


SIZE 


ERR 
PEEK 


POS 


ASC 


LEN 
SUBSTR 


Rounds a real number and converts it to an 
integer. 


Calculates the modulus (remainder) of two 
numbers. 


Returns the absolute memory address of a 
variable, an array, or a structure. 


Returns (in bytes) the storage size of a variable, 
an array, or a structure. 


Returns the error code of the most recent error. 


Returns the byte value at a specified memory 
address. 


Returns the current character position of the 
print buffer. 


Returns the numeric value (ASCII code) of a 
string character. 


Returns the length of a string. 


Returns the starting position of the specified 
substring within a string, or returns 0 if it 
cannot find the substring. 
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Functions performing bit-by-bit logical operations on inte- 
ger or byte data and returning integer results. Do not con- 
fuse these functions with Boolean type operators. 


LAND 
LOR 
LXOR 


LNOT 


Calculates the logical AND of two values. 
Calculates the logical OR of two values. 


Calculates the logical EXCLUSIVE OR of two 
values. 


Calculates the logical NOT of a value. 


Functions returning a result of type string 


CHR$ 


DATE$ 


LEFT$ 


RIGHT$ 


MID$ 


STR$ 
TRIM$ 


Returns the character having a specified ASCII 
value. 


Returns the system’s current date and time. 


Returns the specified number of characters 
beginning at the leftmost character of the 
specified string. 


Returns the specified number of characters 
beginning at the rightmost character of the 
specified string and counting backward. 


Returns the specified number of characters 
starting at the specified position in a string. 


Converts numeric type data to string type. 


Removes trailing spaces from the specified 
string. 


Functions returning Boolean values 


TRUE 
FALSE 
EOF 


Always returns TRUE. 
Always returns FALSE. 


Tests for the end of a disk file. Returns TRUE 
when the end of the file occurs. 


Chapter 8 


Disk Files 


When you tell OS-9 or BASICO9 to store (save) data on a disk, it 
stores the data in a logical block called a file. The term logical 
means that, although the system might store portions of a file’s 
data in several different disk locations, it keeps track of every 
location and treats the scattered data as though it occupied a 
single block. It does this automatically and you never need to 
worry about how the data is stored. File data can be binary 
data, textual data (ASCII characters), or any other useful 
information. 


Because OS-9 handles all hardware input/output devices (disk 
drives, printers, terminals, and so on) in the same manner, you 
can send data to any of these devices in the same way. This 
means you can send the same information to several devices by 
changing the path the data follows. For example, you can test a 
procedure that communicates with a terminal by transferring 
data to and from a disk drive. 


BASICO9 normally works with two types of files—sequential 
files and random access files. The following chart shows file- 
access options, their purposes, and the keywords with which to 
use them: 


Types of Access for Files 


Access Function Use with 

Type 

DIR Opens a directory file for reading. OPEN 
Use only with READ. 

EXEC Specifies that the file to open or OPEN 
create is in the execution directory, CREATE 
rather than the data directory. 

READ Lets you read data from the OPEN 
specified file or device. CREATE 

WRITE Lets you write data to the specified OPEN 
file or device. CREATE 

UPDATE Lets you read data from and write OPEN 
data to the specified file or device. CREATE 
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Sequential Files 


Sequential files send or receive (WRITE or READ) textual data 
in order, the second item following the first, and so on. You can 
access sequential data only in the same order as you originally 
stored it. To read from or write to a particular section of a file, 
you must first read through all the preceding data in the file, 
starting from the beginning. 


BASICO9 stores sequential file data as ASCII characters. Each 
block of data is separated by a delimiter consisting of a carriage- 
return character (ASCII Character 13). Because BASICO9 uses 
this delimiter to determine the end of a record, sequential files 
can contain records of varying length. 


Use the WRITE and READ commands to store and retrieve data 
in sequential files. A WRITE command causes BASICO9 to 
transfer specified data to a specified file, ending the data with a 
carriage return. A READ command causes BASICO09 to load 
from the specified file the next block of data, stopping when it 
reaches a carriage return. 


Sequential File Creation, Storage, and Retrieval 


BASICO9 uses the CREATE command to establish both sequen- 
tial and random access files. A CREATE statement contains: 


@ The keyword CREATE. 


@ A path number variable in which BASICO9 stores the 
number of the path it opens to the new file. 


@ A comma, followed by the name of the file to create. 


e An optional colon, followed by the access mode. If you do 
not specify an access mode, BASICO9 automatically 
opens the created file in the UPDATE mode. 
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The following procedure shows how to create a file and write 
data into it: 


) PROCEDURE makefile 


LIDIM PATH: BYTE (+ establishes a variable 

LIREM for the path number to the file 
LICREATE #PATH, "test": WRITE (+ creates the file TEST 

LIWRITE #PATH,"This is a test" (* writes data to the file 

LIWRITE #PATH,"of sequential files."(* writes another line of data 
LICLOSE #PATH (+ closes the path to the file 
PHELL. “List teat" (* displays the file contents 

LIEND 


The first line of the procedure dimensions a variable (Path) to 
hold the number of the path that CREATE opens. This variable 
should be of byte or integer type. 


When you establish a new file with CREATE, you automatically 
open a path to the file. You do not need to use the OPEN 
command. 


The preceding procedure writes two lines into a file named Test. 

a It then closes the path and uses the OS-9 LIST command to dis- 
play the contents of the newly created file. You see that the data 
is successfully stored on disk. 


The next procedure shows how to reopen an existing file for 
sequential access, read the contents of the file, and append data 
to the end of the file. 


The only way to move the file pointer to the end of a sequential 
file is to read all the data already in the file. Once the pointer is 
at the end of the file, you can add data. 


PROCEDURE append 


LIDIM PATH: BYTE (* dimension variable to hold the number of the 
LIREM path to the opened file. 
CIOPEN #PATH,"test": UPDATE (* open file for reading and writing. 
LIREAD #PATH, line$ (+ read the first element of the file. 
LIREAD #PATH, line$ (+ read the next (the last) element. 
CIWRITE #PATH,"This is a test" (* write one new line to the file. 
=) LIWRITE #PATH,"of appending to a sequential file." (* write another. 
—— LICLOSE #PATH (+ close the path. 
Lionece. “Liat TEST? (+ display the file with the new lines. 
LIEND 
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Because the Test file already exists, this procedure uses OPEN 
to establish a path to the file. It uses the UPDATE mode of file 
access because it needs to both read from and write to the file. 


The two READ statements read the file’s contents and, as a 
result, move the file pointer to the end of the file. The WRITE 
statements then append two new lines. After closing the path, 
the procedure calls on the OS-9 LIST command to display the 
contents of the file, with its appended lines. 


Changing Data in a Sequential File 


You can also change data anywhere in a sequential file. How- 
ever, if your changes are longer than the original data, the oper- 
ation destroys part of the file. To change data in a sequential 
file, read the data preceding what you want to change, and write 
the new data to the file in this manner: 


PROCEDURE replace 
LIDIM PATH: BYTE 
LIOPEN #PATH,"test™:UPDATE 


LIREAD #PATH, line$ 

LIREAD #PATH, lines 

LIWRITE #PATH,"Let’s put new" (+ write over existing 3rd and 
LIWRITE #PATH,"words into the old sequential file.’’ (+ 4th lines. 
LICLOSE #PATH 

SnecL METS TESTS 


LIEND 


Notice that the total amount of data in the two new lines is 
exactly the same as in the two old lines. You can replace an 
existing line with fewer characters by padding the new data 
with spaces. However, if you try to replace existing lines with 
longer lines, the new lines write over and destroy other data in 
the file. 
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INPUT and Sequential Files 


Although you can also use the INPUT command with sequential 
files, doing so might put unwanted data into them. When a pro- 
cedure encounters INPUT, it suspends execution and sends a 
question mark (?) to the screen. This feature makes INPUT both 
an input and output statement. Therefore, if you open a file 
using the UPDATE mode, INPUT writes its prompts to the file, 
destroying data. If you specify text to be displayed with the 
INPUT command, INPUT writes this text to the file also. 


Random Access Files 


Random access files store data in fixed- or equal-length blocks. 
Because each record in a specific file is the same size, you can 
easily calculate the position of a record. 


For instance, suppose you have a file with a record length of 50- 
bytes (or characters). To access Record 10, multiply the record 
number (10) by the record length (50) and move the file pointer 
to the calculated position (500). 


A random access file sends and receives data (using PUT and 
GET) in a binary form, exactly as BASICO9 stores it internally. 
This feature minimizes the time involved in converting the data 
to and from ASCII representation, as well as reducing the file 
space required to store numeric data. You position the random 
access file pointer using SEEK. Compared to sequential file 
access, random file access using GET and PUT is very fast. 


Using random access commands, you can store and retrieve indi- 
vidual bytes, strings of bytes, individual elements of arrays or 
total arrays with one PUT or GET command. When you GET a 
structure, you recover the number of bytes associated with that 
type of structure. 


This means when you GET one element of byte type data, you 
read one byte. When you GET one element of real type data, you 
read five bytes. If you GET an array, you read all the elements of 
the array. This potential for reading entire arrays at once can 
greatly speed disk access. 


As well as moving the file pointer to the beginning of individual 
records, you can also move it to any position within a record and 
begin reading or writing one or more bytes from that point. 
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Creating Random Access Files 


You create and open random access files in the same way you 
create and open sequential files. The only differences are in the 
commands you use to store and retrieve the data and in the 
manner you keep track of where elements, or records, of a file 
begin and end. 


Before you can write data to a random access file, you must 
either CREATE it or open it in the WRITE or UPDATE mode. 
Once you have a path open to an existing file, use PUT to write 
data into the file. If you open the file in the READ or UPDATE 
mode, you can then use the GET command to retrieve data from 
the file. 


The PUT command can use only one parameter, the name of the 
data element to store. The parameter can be a string, a variable, 
an array, or a complex data structure. 


Before storing data, you must devise a method to store it in 
blocks of equal size. Knowing the unit size lets you later retrieve 
the data in its original form. The following procedure shows one 
way to do this: 


PROCEDURE putget 
OREM This procedure creates a file named Test1, reads 10 data lines, 
CREM PUTS them into the file, then closes the file. Next it 

DREM opens the file in the READ mode, GETS stored lines and lists 


DREM them on the display screen. 


CIDIM LENGTH: BYTE 
CIDIM NULL: STRING(25]} 
DDIM LINE:STRING(25] 
KIDIM PATH: BYTE 
LILENGTH=25 

UNULL="" 

CIBASE 9 

CON ERROR GOTO 18 

LIDELETE "testi" (+ if the file exists, delete it. 
1@L0N ERROR 


CICREATE #PATH,"testi":WRITE (* create a file named testi. 


CIFOR T=0 10 9 

LISEEK #PATH,LENGTH#T (+ find beginning of each file. 
CIREAD LINE$ (+ read a line of data. 

LIPUT #PATH,LINE$ (* store the line in the file. 
LINEXT T 
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TICLOSE #PATH (+ close the file. 

LIOPEN #PATH,"test1":READ (+ open the file for reading. 

CIFOR T=@ T0 9 

CISEEK #PATH,LENGTH#T (+ find the beginning of each file. 
LIGET #PATH,LINE (# gel a line from the file. 
LIPRINT LINE (+ display the line. 

CINEXT T 

LICLOSE #PATH (+ close the file. 

CEND 


KIDATA "This is test line #1" 
CIDATA "This is test line #2" 
OIDATA "This is test line #3" 
KIDATA "This is test line #4" 
LIDATA "This is test line #5" 
KIDATA "This is test line #6" 
LIDATA "This is test line #7" 
LIDATA "This is test line #8" 
DDATA "This is test line #9" 
DDATA "This is test line #10" 


This procedure creates a file named Test1. The variable named 
Length stores the length of each line in the file (25 characters). 
The string variable Null, is a string of 25 space characters. The 
variable Line contains the data to store in each element (record) 
in the file. The variable Path stores the path number of the file. 


Next, the procedure contains an ON ERROR routine that deletes 
the file Test1, if it already exists. Without this routine, the pro- 
cedure produces an error if you execute it more than once. 


Next, the routine uses CREATE to open the file Test1. The line 
SEEK #PATH, LENGTH*T sets the file pointer to the proper loca- 
tion to store the next line. Because Length is established as 25, 
the file lines are stored at 0, 25, 50, 75, and so on. 


After the routine initializes storage space, it begins to store 
data by reading the procedure data lines one at a time, seeking 
the proper file location, and putting the data into the file. After 
storing all 10 lines, it closes the file. 
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The last part of the routine opens the new file, uses the same 
SEEK routine to position the file pointer, and reads the lines 
back, one at a time, to confirm that the store routine is 
successful. 


The next short routine shows how you can use a procedure to 
read any line you select in the file, without reading any preced- 
ing lines: 


PROCEDURE randomread 
LIDIM LENGTH: BYTE 
CIDIM LINE: STRING([25] 
LIDIM SEEKLINE:BYTE 
DDIM PATH:BYTE 
KILENGTH=25 


LIOPEN #PATH,"test1":READ (# open the file for reading. 
CILOOP 

INPUT "Line number to display...",SEEKLINE (* type a line to get. 
DIEXITIF SEEKLINE>1@ OR SEEKLINE<1 THEN (* test if record is valid. 


DENDEXIT (+ exit loop if not. 

LISEEK #PATH, (SEEKLINE-1)*LENGTH (+ find the requested record. 
LIGET #PATH,LINE (# read the record, 

DPRINT LINE (+ display the record, 

DPRINT 

LIENDLOOP 

LIPRINT "That’s all ....... a (* end session, 

OICLOSE #PATH (+ close path. 

DEND 


The procedure asks for the record number of the line to display. 
When you type the number (1-10) and press (ENTER), SEEK moves 
the file pointer to the beginning of the record you want, GET 
reads it into the variable Line, and PRINT displays it. The cal- 
culation (SEEKLINE-1)*LENGTH determines the beginning of 
the line you want. If you type a number outside the range of 
lines contained in the file (1-10), the procedure drops down to 
Line 100 and ends. 


By changing this procedure slightly, you can replace any line in 
the procedure with another line. The altered procedure below 
demonstrates this: 
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PROCEDURE random__replace 
LIDIM LENGTH: BYTE 

LIDIM LINE: STRING(25] 

LIDIM SEEKLINE: BYTE 
LIDIM PATH: BYTE 


LILENGTH=26 


KOPEN #PATH,"testi":UPDATE(* open the file. 
LILOOP 


KINPUT "Line number to display...",SEEKLINE (+ type record to find. 
DEXITIF SEEKLINE®1@ OR SEEKLINE<1 THEN (* test if valid number. 


LIENDEXIT (+ exit loop if not 

OSEEK #PATH,(SEEKLINE-1)#LENGTH (# find the requested record. 
LIGET #PATH,LINE (+ get the data. 

LIPRINT LINE (+ print the record. 

LIPRINT 


KINPUT "Type new line... ",LINE (# type a new line. 
CSEEK #PATH,(SEEKLINE-1)#LENGTH (* find beginning of the record. 


LIPUT #PATH,LINE (* store the new line. 
CIENDLOOP (+ do it all again. 
PIPRING “That's al) sateisa 4 (+ terminate procedure. 
CICLOSE #PATH (+ close path. 

CEND 


This time, the file is opened in the UPDATE mode to allow both 
reading and writing. You type the line you want to display. A 
prompt then asks you to type a new line. The procedure 


exchanges the new line for the original line, and stores it back in 
the file. 


Using Arrays With Random Access Files 


BASIC09’s random access filing system is even more impressive 
when used with data structures, such as arrays. Instead of using 
a loop to store the 10 lines of the Random_replace procedure, 
you could store them all at once, into one record, using an array. 
The following procedure illustrates this: 
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PROCEDURE arraywrite 

LIDIM LENGTH: BYTE 

LIDIM LINE: STRING(25] 

CIDIM RECORDC18):STRING(25] 
LIDIM PATH: BYTE 

LILENGTH=25 


LION ERROR GOTO 18 
LIDELETE "testi" 
18LJON ERROR 


LICREATE #PATH,"test1":WRITE 
LIBASE @ 


LIFOR T=8 TO 9 
LIREAD RECORD(T) 
LINEXT T 


LISEEK #PATH, 0 
LIPUT #PATH,RECORD 
LICLOSE #PATH 


LOPEN #PATH,"testi":READ 
LIFOR T=8 TO 9 

LISEEK #PATH, LENGTH#T 
LIGET #PATH,LINE 

LIPRINT LINE 

LINEXT T 

PICLOSE #PATH 

LIEND 


DIDATA "This is test line #1" 
OIDATA "This is test line #2" 
ODATA "This is test line #3" 
DDATA "This is test line #4" 
ODATA "This is test line #5" 
CIDATA "This is test line #6" 
ODATA "This is test line #7" 
CIDATA "This is test line #8" 
ODATA "This is test line #9" 
UIDATA "This is test line #10" 
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(* delete Test! if it exists. 


( 


od 


create Testi, 


(* Read data lines into RECORD array, 


(+ set pointer to beginning of file. 
(* store the entire array into file, 
(+ close path to file. 


(+ open the file to read, 
(* find each element. 


(+ read an element. 
(+ print the element. 
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This procedure reads the 10 lines into an array named Records. 
Then it places the entire array in the Testl file, using one PUT 
statement. To show that the structure of the file is still the 
same, the original FOR/NEXT loop reads the lines, one at a 
time, and displays them. 


Notice that, because you need to write only one element, you can 
set the file pointer to 0 (SEEK #PATH,@). You can rewind a file 
pointer (set it to 0) at any time in this manner. 


You could save additional programming space by also reading the 
10 lines back into memory as an array. The following procedure 
uses a new array, Readlines, to call the file back into memory, 
and displays the lines. 


PROCEDURE arrayread 

LIBASE @ 

LIDIM READLINES(10):STRING(25] 
LIDIM PATH: BYTE 


KOPEN #PATH,"test1":READ (+ open file. 
LIGET #PATH,READLINES (+ read file into array, 
CICLOSE #PATH 


LIFOR T=@ 10 9 

LIPRINT READLINES(T) (+ print each element of the array. 
LINEXT T 

LIEND 


Using Complex Data Structures 


In the previous section, you stored and retrieved elements of an 
array that were all the same size, 25 characters. Often you need 
to store elements of varying sizes, such as when you create a 
data base program with several fields in one record. 


The following examples create a simple inventory system that 
requires a random access file having 100 records. Each record 
includes the name of the item (a 25-byte string), the item’s list 
price and cost (both real numbers), and the quantity on hand (an 
integer). 
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First, you use the TYPE command to define a new data type 
that describes such a record. For example: 


TYPE. TNVezTTEM*NAMESSTRINGL 2515 LIST,cCOSTsREAL: 
aT Ys INTEGER 


Although this statement describes a new record type called 
Inv_item, it does not assign variable storage for the record. The 
next step is to create two data structures: an array of 100 rec- 
ords of type Inv_item named Inv_array and a working record 
named 

Work_rec. The following lines do this: 


DIM INV_ARRAYC108):INV_ITEM 
DIM WORK__REC: INV_ITEM 


To determine the number of bytes assigned for each type, you 
can use BASICO09’s SIZE command. SIZE returns the number of 
bytes assigned to any variable, array, or complex data structure. 
For example, the command line SIZECWORKI__REC) returns the 
number 37. The command SIZECINV_ARRAY) returns the num- 
ber 3700. 


You can use SIZE with SEEK to position a file pointer to a spe- 
cific record’s address. 


The following procedure creates a file called Inventory and 
immediately initializes it with zeroes and null strings. Five 
INPUT lines then ask you for a record number and the data to 
store in each field of the record. You can fill any record you 
choose, from 1 through 100. 


When one record is complete, the procedure uses PUT to store 
the record. Then, it asks you for a new record number. If you 
wish to quit, enter a number either larger than 100 or smaller 
than 1. 


PROCEDURE inventory 

LIREM Create a data type consisting of a 25-character name field, 
DREM a real list price field, a real cost field, and an integer 
OREM quantity field. 

LITYPE INV__ITEM=NAME:STRING(25]; LIST,COST:REAL: QTY: INTEGER 


CIDIM INV__ARRAY(100):INV__ITEM (# dimension an array using new type. 
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CIDIM WORK__REC: INV__ITEM 
CREM (* dimension a working variable of the new type. 
LIDIM PATH: BYTE 


LION ERROR GOTO 10 
LIDELETE "inventory" 
{@QJ0N ERROR 


LICREATE #PATH, "inventory" (+ create a file named Inventory. 
LIWORK__REC.NAME="" " (+ set all data elements to null or @. 
LIWORK__REC.LIST=0 

LIWORK__REC.COST=0 

LIWORK__REC.QTY=0 

LIFOR N=1 TO 108 

LIPUT #PATH ,WORK__REC 

LINEXT N 


LILOOP 

LIINPUT "Record number? ",RNUM (# enter number of record to write. 
LIF RNUM<1 OR RNUM>10@ THEN (* check if number is valid. 
LIPRINT 

LIPRINT "End of Session" (* if not, end session. 

LIPRINT 

LICLOSE #PATH 

LIEND 

LIENDIF 

KUINPUT "Item name? ",WORK__REC.NAME (+ type data for record, 
DINPUT "List price? ",WORK__REC.LIST 

KIINPUT "Cost price? ",WORK_REC.COST 

KIINPUT "Quantity? ",WORK_REC. QTY 

LISEEK #PATH, CRNUM-1)#SIZECWORK__REC) (# find record. 

LIPUT #PATH ,WORK__REC (# write record to file. 
HIENDLOOP 


Notice that the INPUT statements reference each field sepa- 
rately, but the PUT statement references the record as a whole. 


The next procedure lets you read any record in your Inventory 
file, and displays that record. If you ask for a record you have not 
yet filled with meaningful data, the display consists of a null 
string and zeroes. 


PROCEDURE readinv 
LITYPE INV__ITEM=NAME:STRING([25]; LIST,COST:REAL: QTY:INTEGER 
LIDIM WORK__REC: INV__ITEM 


8-13 


BASIC09 Reference 


LIDIM PATH:BYTE 

LJOPEN #PATH, "INVENTORY": READ 
LILOOP 

CIINPUT "Record number to display? ",RNUM 
CIF RNUM<1 OR RNUM>100 THEN 

DPRINT “End of Session" 

DIPRINT 

LICLOSE #PATH 

LIEND 

LIENDIF 

LISEEK #PATH, C(RNUM-1)#SIZE(WORK__REC) 
LIGET #PATH,WORK__REC 

LIPRINT "#" "Item", "List Price","Cost Price", "Quantity" 

LIPRINT "nnn nn nnn nn nnn nnn nnn renee nnn nner nn nnn nnn en nen nee en en nee e eee ee 


LIPRINT RNUM,WORK__REC.NAME ,WORK__REC.LIST,WORK__REC. COST ,WORK__REC. QTY 
LIPRINT 

LIENDLOOP 

LIEND 


This procedure accesses the file one record at a time. It is not 
necessary to do so. You can read the entire file into memory at 
once by dimensioning an inventory array and getting the whole 
file into it: 


LITYPE INV__ITEM=NAME:STRING(25]; LIST,COST:REAL; QTY: INTEGER 
LIDIM INV__ARRAY(100): INV__ITEM 

LISEEK #PATH,@  (#rewind the file) 

LIGET #PATH, INV__ARRAY 


The examples in this section are simple, yet they illustrate the 
combined power of BASICO9 complex data structures and the 
random access file statements. They show that a single GET or 
PUT statement can move any amount of data, organized in any 
way you want. Other advantages are of using complex data struc- 
tures are: 


@ The procedures are self-documenting. You can see easily 
what a procedure does because its structures can have 
descriptive names. 


@ Execution is extremely fast. 


@ Procedures are simple and usually require fewer state- 
ments to perform I/O functions than other BASICs. 
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@ The procedures are versatile. By creating appropriate 

data structures, you can read or write almost any kind 

‘- of data from any file, including files created by other pro- 
<0 grams or languages. 


Chapter 9 


Displaying Text and Graphics 


BASICO9 has three levels of graphics capabilities. The first and 
third levels can include both graphics designs and text. The sec- 
ond level can display only graphics designs. 


ASCII Codes 


For low-resolution text screens and high-resolution text and 
graphic screens, BASICO9 uses ASCII (American Standard Code 
for Information Interchange) codes to represent the common 
alphanumeric characters. ASCII is the same code that most 
small computers use. 


A table of the standard codes follows: 


Table 9.1 
BASIC09 ASCII Codes 0-127 
Low- and High-Resolution Screens 


Character Decimal Code Hexadecimal Code 
03 03 
8 O8 
9 O9 
10 OA 
CLEAR 12 OC 
13 OD 
Space 32 20 
! 3a PA 
" 34 22 
# 35 23 
$ 36 24 
% 37 20 
& 38 26 
39 27 
( 40 28 
) 41 29 
* 42 2A 
-- 43 2B 
44 2C 
. 45 2D 
46 2E 
/ 47 2F 
0 48 30 
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Character 


OMmoNIHILhWNrFR 


SSI CHMADVOAZSOCAGH TEOMA OGCAOWPOe~rV il Av - 


xX 
¥ 
Z 
[ (GH) 
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Decimal Code 


49 
50 
ol 
o2 
o3 
o4 
DD 
56 
o7 
08 
o9 
60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
70 
71 
12 
73 
74 
75 
76 
T¢ 
78 
2 
80 
81 
82 
83 
84 
85 
86 
87 
88 
89 
90 
v1 


Hexadecimal! Code 


31 
32 
33 
34 
35 
36 
37 
38 
39 
3A 
3B 
3C 
3D 
3E 
oF 
40 
Al 
42 
43 
dd 
45 
46 
47 
48 
AQ 
4A 
4B 
4C 
AD 
4K 
AF 
50 
ol 
O2 
O3 
o4 
ye) 
56 
o7 
08 
59 
5A 
5B 
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Character Decimal Code Hexadecimal Code 
Fa \. ((SHIFT ](CLEAR }) 92 5C 
| ] ((SHIFT }(>)) 93 5D 
rN 94 5E 
—> ((SHIFT ]{ 4 }) 95 bE 
~ 96 60 
a 97 61 
b 98 62 
¢ 99 63 
d 100 64 
e 101 65 
f 102 66 
g 103 67 
h 104 68 
i 105 69 
j 106 6A 
k 107 6B 
] 108 6C 
m 109 6D 
n 110 6E 
cy O Lid 6F 
p 112 70 
q 113 Tl 
r 114 12 
S 115 73 
t 116 74 
u L17 10 
V 118 76 
w 119 (ei 
x 120 78 
y 121 79 
Z 122 TA 
{ 123 7B 
| 124 iG 
} 125 TD 
% 126 7E 
— 127 7F 


>» You can generate the characters in this chart by pressing the 
appropriate key, or you can generate them from BASICO9 using 
the CHR$ function. 


9-3 


BASICO09 Reference 


Low-Resolution Graphic Characters 


In addition to alphanumeric characters, low-resolution graphics 
also offers graphic characters. Generate these characters by 
pressing at the same time you press a keyboard character. 
The graphics character codes are in the range 128-255. 


Pressing while pressing another key, causes OS-9 to add 
128 to the ASCII value of the second key. (For the technically 
minded, OS-9 sets the high bit of the character code.) Therefore, 
if you press [A], you produce graphics character 193. You can 
also generate graphics characters from BASICO9 using the 
CHR$ function, and you can PRINT them in the same manner 
as other characters. 


Low-level graphics characters follow a pattern that repeats every 
16 characters. Table 9.2 shows the first set of graphic characters, 
128-143. Subsequent characters produce the same series of con- 
figurations but display in different colors, as shown in Table 9.3. 


Table 9.2 
Low-Resolution Graphic Character Set 


Character Code Character Code Character Code Character Code 


128 136 140 
129 133 137 141 
130 a” 134 138 142 
131 alll 135 | 139 | | 143 
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Table 9.3 
Low-Resolution Graphics Color Set 


ASCIT Code Graphics Block Color 


128 - 143 Black and Green 

144 - 159 Black and Yellow 

160 - 175 Black and Blue 

176 - 191 Black and Red 

192 - 207 Black and Buff 

208 - 223 Black and Light Blue 

224 - 239 Black and Cyan 

240 - 254 Black and Orange 
Zoo Green 


Within each color set, you can easily calculate the number for a 
particular character. For instance, suppose you want to print a 
character that has orange upper left and lower right corners. Pic- 
ture the character divided into four sections, numbered as 
follows: 


To calculate a character that has orange at Sections 8 and 1, add 
the section values to the first value in the orange group, 240, 
like this: 


240 + 8+ 1 = 249 
Character 249 is what you want. 


The following diagram shows how you might block out a large 
letter O on the screen. The shaded portions of the characters are 
colored. The unshaded portions are black. In this case we want 
the colored portions to be green (the same color as the screen). 
You can do this using the color set 128 - 143. 
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Because Section 1 in the upper left character is to be colored, 
add 1 to the initial character value of 128. The first character 
value is 129. Moving right, Sections 2 and 1 are colored in the 
second character. Add 3 to 128 to get a second character value of 
131. Calculate all 15 characters in this manner. 


You could create a letter O in a BASICO9 procedure by printing 
each of the five rows of three characters. You could use DATA 
lines to store the ASCII codes for each character, then use loops 
to read and display the characters they represent. 


Although low-level graphics is very rough, it can be useful, and 
it lets you mix graphics with text. 


The following procedure not only creates the letter O, it adds the 
letter S and the number 9 to display the name of your operating 
system. 
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PROCEDURE os9prog 
ODIM DAT: INTEGER 
TPRINT CHR$C€12) 
OPRINT 

OPRINT 

OPRINT 

OFOR Z=1 TO 5 


UPRINT TABC18); 

UFOR T=1 TO 12 

UREAD DAT 

UIPRINT CHRS$CDAT); 

IAEA OT 

PRINT 

INERT 32 

LEND 

ORT: TES. 1St 41 e0y TAS. 1203 1319 1.31 o 1 4Sg Tees 13ST 4 rats 
143 

LOATA, 1334 14351384 17935733514935174934 1934132, 190s 1se4 
143 


IDATO 133314351384 14341-3245 1.405 140514541314 131413905 
o-~ 143 

UDATA 1334143; 13851435133 4131413051 435414351934.1 36% 

143 

UDATA: tae4 1905136, 149351404140, 13651493,143,19355138, 

143 
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Special Characters in High-Resolution 


High-resolution graphics does not have graphic characters but it 
does have other international and special characters. These char- 
acters are represented by ASCII codes 128 through 159 as shown 
in the following table: 


Table 9.4 
High-Resolution Special Characters 
Hex Decimal Hex Decimal 
Character Code Code Character Code Code 
C 80 128 6 90 144 
u 81 129 ae 91 145 
é 82 130 my 92 146 
a 83 les w! 6 93 147 
a 84 132 6 94 148 
a 85 133 Dg 95 149 
a 86 134 a 96 150 
C 87 135 u 97 151 
é 88 136 Q 98 152 
é 89 137 O 99 153 
é 8A 138 O 9A 154 
i 8B 139 § 9B 155 
n 8C 140 £ 9C 156 
Ff) 8D 141 = 9D L57 
A 8E 142 ° 9K 158 
A 8F 143 f OF 159 


Medium-Resolution Graphics 


For more sophisticated graphics operations, OS-9 has built-in 
graphics interface modules that provide a convenient way to 
access the graphics and joystick functions of the Color Computer 
3. The required module for medium-resolution graphics is named 
GFX. It must be in your execution directory or resident in mem- 
ory when called by BASICO9. 


You can either install GFX in memory using the LOAD com- 
mand, or wait until BASICO9 calls it for a graphics function. 
Once loaded, GFX resides in memory until you remove it using 
the OS-9 UNLINK command or the BASICO9 KILL command. 
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GFX has a number of functions that you pass to it as parame- 
ters with the RUN statement. For instance, the following state- 


ment clears the current graphics screen: 


RUN GFXC™CLEAR") 


Other tasks need such parameters as position, color, and size. 
The following is a quick reference to all of the GFX functions. 
Each is explained in detail later: 


Function 


ALPHA 


CIRCLE 


CLEAR 


COLOR 


GCOLR 


GLOC 


JOYSTK 


LINE 


MODE 


MOVE 


Purpose 


Sets the screen to the 
alphanumeric mode. 


Draws a circle. 


Clears the screen to a 
color. 


Changes the foreground 
and background colors. 


Reads a pixel’s color. 


Returns a video display 
address. 


Returns the joystick 
button and X- and Y- 
coordinate status. 


Draws a line. 


Switches the screen 
between alphanumeric 
and graphics, sets the 
graphics screen color. 


Positions the invisible 
graphics cursor. 


Parameters 


None. 


Radius, optional X- and 
Y-coordinates, and color. 


Optional color for screen. 


Foreground and 
background colors. 


Names of variables in 
which to store optional 
X- and Y-coordinates. 


None. 


Names of variables in 
which to return the 
values. 


Ending X- and Y- 
coordinates, optional 
beginning coordinates, 
optional color. 


Format, Color. 


X- and Y-coordinates. 
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Function Purpose Parameters 

POINT Moves graphics cursor X- and Y-coordinates 
and sets a point. and optional pixel color. 

QUIT Returns screen to None. 


alphanumeric mode. 
Deallocates graphics 
memory. 


Formats and Colors 


In medium-resolution graphics, you have a choice of two formats. 
Format 0 provides 256 horizontal points by 192 vertical points. In 
this format, you can have only two colors on the screen at a time. 


Format 1 provides a 128 by 192 point screen and a maximum of 
four colors on the screen at a time. OS-9 medium-resolution 
graphics treats the screen as if it were a grid, with coordinate 
0,0 at the lower left corner as shown in the following illustration. 
All points on the grid are positive. 


OS a ea 
0, X-coordinate 


BASICO9 defines colors with numbers or color codes. Many GFX 
functions allow or require color codes as parameters. BASICO9 
also divides the color codes into color sets. Specifying a color code 
outside the current color set automatically initializes the new 
set. 


9-10 


ww 


Displaying Text and Graphics / 9 


Back- Fore- 
ground | ground 


Format 0 


Fore- 
ground | ground 


Black 
Green 


Buff 
Cyan 

Magenta 
Orange 


Black 
Dk Green 
Md Green 
Lt Green 


Table 9.5 


Use the preceding charts to chose colors for those functions that 
let you specify foreground or background colors. For instance, to 
initialize a Format 1 graphics screen with a green background 
and a red foreground, you type: 


run gfxC"mode",1,3) 


The following reference section describes all the medium-resolu- 
tion graphics functions, and provides examples and sample pro- 
grams. To understand the organization of the commands 
reference, see “The Syntax Line” in Chapter 11. 
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The Draw Pointer 


Medium-resolution graphics uses a draw pointer, or invisible 
graphics cursor, to determine what area of the screen is affected 
by graphics operations. When you establish a graphics screen, 
the draw pointer is located at coordinates 0,0. Some graphic 
functions automatically change the pointer location on the 
screen. For instance, the LINE function moves the draw pointer 
from the beginning coordinates to the end coordinates. 


Because some functions begin at the draw pointer, you need to 
keep track of its location and make certain it is placed properly. 
Use the MOVE function to set the draw pointer to new locations. 
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ALPHA Select alphanumeric screen 


Syntax: RUN GFX(“ALPHA”) 


Function: Switches from the graphics screen to the alphanu- 
meric (text) screen. The current graphics screen remains 
intact. 


Parameters: None 


Examples: 
RUN GFXC™ALPHA") 


Sample Program: 


This procedure lets you choose to draw a circle or rectangle of 
the size you select. Once you choose the shape and size, it uses 
the MODE function to select a graphics screen. When the shape 
is complete, you press to return to a text screen. The pro- 
cedure uses the ALPHA function to return to the original menu. 


PROCEDURE alpha 

DDIM XCOR.YCOR.SIDE1,SIDE]2], RADIUS; 7%. ¥,2¢INTEGER 
ODIM RESPONSE:STRING([1] 

18 REPEAT 

SHELL. “DISPLAY #c™ 

OPRINT "Do you want to draw" 

UPRINT “13 A rectangle” 

LPRINT “223. 4 eirele”™ 


OPRINT " -Press 1 or 2...""3 

UGET #@,RESPONSE 

OPRINT 

ULF RESPONSE="1" THEN 

INPUT “Lengtin OF Sid@ 156." ,Si1DEt 
DENPUT. “Lengin of Side 255.%,S1DE2 


URUN GFXC™MODE",@,9) 

URUN GFXC™CLEAR") 

UXCOR=10 

LIYCOR=19 

LRUN GEXC™LINE”, XCOR; YCORsXCOR+S1DE1s YCOR 1.2 
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IRUN GEAC™LINE”, XCGR*#SIDET, YCOR, XCUR*#S IDET. YOUR* 
2IDEG +42 

DRUN: GFXCeLINE”’  XCOR*S IDET, YCOR+S DES, XCUR, YCUR* 
SLVee ae 

DRUN GFXC "LINE, XCOR;, YCOR+SI DES, XCOR, YCOR,1 9 
UINPUT RESPONSE 


JEL SE 
He KESPOnSc ="2”"- Taen 
UINPUT “What radius?...™",RADIUS 


URUN GFXC™MODE",@,1) 

URUN GFXC"™CLEAR") 

ORUN GFXC™CIRCLE”,128,98,RADIUS) 
LISPUT RESPONSE 

LENDIF 

UENDIF 

LJUNTIC RESPONSE <3*°7" AND. RESPONSE<> "2" 
LIRUN GFXC™ALPHA") 

UGOTO 18 

WEND 
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CIRCLE Draw a circle 


Syntax: RUN GFX(“CIRCLE”[,xcor,ycor],radius [,color]) 


Function: Draws a circle of a given radius. If you do not spec- 
ify a color, BASICO9 uses the current foreground color. If you 
do not specify X- and Y-coordinates, CIRCLE uses the current 
graphics cursor position as the circle’s center. 


Parameters: 
radius The radius of the circle you want to draw. 
color The code of the color you want the circle to be. 
See the chart earlier in this section for color 
information. 
xcor,ycor The X- and Y-coordinates for the center of the 
circle. Specifying coordinates outside the X- 
coordinate range of 0-255 or outside the Y- 
coordinate range of 0-191 causes an error. 
Examples: 


RUN GFXC™CIRCLE",100) 
RUN GFXC™"CIRCLE",100,3) 
BUN GEAC™CUTROULE" 125. 180,188) 


RUN GFXC™CIRCLE™ 125,180,108, 2) 


Sample Program: 


This procedure uses CIRCLE to draw and erase a circle. The 
location of the circle changes before each draw/erase operation, 
causing the circle to move. When it hits the edge of the screen, 
it reverses its direction at a random angle and bounces. 


PRUCEDURE cireles 

ODIM RADIUS,XCOR,YCOR: INTEGER 
UDIM XTEMP,YTEMP: INTEGER 

LIDIM PATH1,PATH2@: INTEGER 

UDIM FLAG: INTEGER 
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LFLAG=1 

UXCOR=5 

UYCOR=5 
UPATH1=RNDC15)+2 
UIPATH2=RNDC18@)+2 
UXTEMP=249 
LYTEMP=185 

URUN GFXC™MODE",@,1) 
URUN GFXC"™CLEAR") 
UFOR T=1 TO 209 
OWHILE XCOR<25@ AND XCOR>4 AND YCOR<186 AND YCOR>4 
DO 

UIRUN. GCF XAC’™CTROLE*. 2TEMP, YIEMP 3 5.82 
OIRUN OF XC™CIRCLE™, XCOR, YCOR,3319 
UXTEMP=XCOR 
LYTEMP=YCOR 
UXCOR=XCOR+PATH1 
LYCOR=YCOR+PATH2 
UENDWHILE 

LIPATH1 =RNDC15)+2 
UPATH2=RNDC19)+2 

DIF XCOR>249 THEN 
UxXCOR=249 

DENDIF 

HIF XCOR<S THEN 
UXCOR=5 

LJENDLF 

DIF YCOR>18S THEN 
UYCOR=185 

UENDIF 

HIF YCOR<S THEN 
UYCOR=5 

JEND LF 

LIFLAG=FLAG*-1 

DIF FLAG<@ THEN 
LIPATH1 =PATH1*-1 
UPATH2=PATH2+*-1 
UENDIF 

UNEXT T 

UEND 
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CLEAR Clear the screen 


om 

Syntax: RUN GFX(“CLEAR”(,color)) 

Function: Clears the current graphics screen. If you do not 
specify a color, CLEAR sets the entire screen to the current 
background color. CLEAR also sets the graphics cursor at 
coordinates 0,0, the lower left corner of the screen. 

Parameters: 
color A code indicating the color to set the screen. 

Examples: 

RUN GFXC™"CLEAR") 
RUN GFAC™CLEAR™, 1429 
om 
o™ 
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COLOR Change the foreground color 


Syntax: RUN GFX(“COLOR’”,color) 


Function: Changes the foreground color (and possibly the color 
set). COLOR does not change the graphics format or the cur- 
sor position. 


Parameters: 
color A code indicating the color you want for the 
foreground. See the chart earlier in this chap- 
ter for color information. 
Examples: 


RUN GPAC™’COLOK”™, 1202 


Sample Program: 


This procedure connects a series of differently colored circles to 
produce a necklace effect. 


PROCEDURE necklace 

OBIS COLOR; TatlsJd.,8,FLAG.ACOR, YCOR: INTEGER 
RUN. GEFXAC "MODE ..7.82 

DORUN GFXC™CLEAR") 

(iCOLOR=1 
UXCOR=1 

UYCOR=1 

UR=2 

FOR T#1 TO & 
(FOR J=1 TO 48 
UXCOR=XCOR+1 
HYCOR=YCOR+.8 
OIF FLAG<@ THEN 
UR=R-1 

HE LSE 

UR=R+1 

LIENDIF 

UCOLOR=COLOR+1 

OIF COLOR>3 THEN COLOR=1 
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fr NEXT J 
NEXT T 
OFOR U=1 
NEXT U 
TEND 


LFLAG=FLAG*- 1 


TO 10080 
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ORUN GFXC™ CIRCLE”, XCOR,YCOR;R,COLOR)D 
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GLOC Find the graphics screen location 


Syntax: RUN GFX(“GLOC”,storage) 


Function: Determines the location of the graphics screen in 
memory and returns the address in the specified variable. 
When you know the graphic screen address, you can use 
PEEK and POKE to perform special functions not available in 
the GFX module, such as filling a portion of the screen with a 
color or saving a graphics screen to disk. 


OS-9 Level Two maps display screens into a program’s 
address space before PEEK and POKE can operate on a dis- 
play screen. This means that you must have at least eight 
kilobytes of free memory in the user’s address space. Program 
and data memory requirements must not exceed 56 kilobytes. 


Parameters: 
storage An integer or byte type variable in which 
GLOC stores the memory address of the 
graphics screen. 
Examples: 


RUN GFXC"GLOC", location) 


Sample Program: 


This procedure uses the GLOC function to locate the current 
graphics screen, then uses POKE to paint a series of boxes on 
the screen. 


PROCEDURE boxin 

UJDIM LOCATION,PLACE,COLOR,BEGIN,QUIT,X,TERMINATE, 
GLNE gl aved ht EGER 

HRUN: GEAC™ MODE 45.09 

URUN GFXCPCLEAR™) 

URUN GFXC"GLOC™,LOCATION) 

JLOCATION=LOCATION+10@ \ PLACE=LOCATION 

UBEGIN=1 

JQUIT=88 
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UCOLOR=255 
UTERMINATE=16 

ULINE=32 

UFOR X=#1 TO 4 

UFOR T=1 TO QUIT 

OUFOR J=BEGIN TO TERMINATE 
UPOKE PLACE+J,COLOR 
UNEXT J 
UPLACE=PLACE+LINE 
NEAT 1 
ULOCATIOQN=LOCATION+160 
UBEGIN=BEGIN+1 
LUIPLACE=LOCATION 
HQUIT=QUIT-18 
UTERMINATE=TERMINATE-1 
UCOLOR=COLOR-85 

UNEXT xX 

UINPUT 2$ 

UEND 
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oJ OYSTK Get joystick status 


Syntax: RUN GFX(“JOYSTK”, stick, fire,xcor,ycor) 


Function: Determines the status of the specified joystick fire 
button and the X,Y position of the specified joystick handle. 
Use this function only with a standard joystick or mouse, not 
with the high-resolution mouse adapter. 


Parameters: 


stick 


fire 


xcor,ycor 


Examples: 


The joystick (0 or 1) for which you want to 
determine the status. 0 indicates the right joy- 
stick, 1 indicates the left joystick. 


A variable in which JOYSTK returns the sta- 
tus of the specified fire button. Fire can be 
byte, integer, or Boolean type. A value other 
than 0 or TRUE indicates the button is 
pressed. 


Byte or integer type variables in which 
JOYSTK stores the X- and Y-coordinates of 
the joystick handle position. The coordinate 
range is 0-63. 


RUN GFXC™JOYSTK",@,shoot,x,y) 
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Sample Program: 


This procedure uses the JOYSTK function to draw on the screen 
with the right joystick. 


PROCEDURE joydraw 

DIM STICK,FIRE.xXCOR. YCOR,XTEMPs YTEMPSINTECER 
URUN GFAC@MEDE™. 8,12 

UIRUN GPAC’? CLEAR) 

UJOY=@ \XCOR=@ \YCOR=9@ 

HREPEAT 

UXTEMP=XCOR 

LIYTEMP=YCOR 

URUN: OF Se" JOY STR, 8. FIRE. ACUR.VCUR) 
UXCOR=XCOR*4 

LIYCOR=YCOR*4 

URGN <GPAC™LINE™  XTEMP YTEMP.. XCOR,YCORD 
UNTIL FIRE<>@ 


UEND 
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LINE Draw a line 


Syntax: RUN GFX(“LINE”[,xcorl1,ycor!],xcor2,ycor2 
[,color]) 


Function: Draws a line in the current or specified foreground 
color in one of the following ways: 


e From the current draw position to the specified X,Y- 
coordinates. 


@ From the specified beginning X- and Y-coordinates to the 
specified ending X, Y-coordinates. 
Parameters: 
xcor1 ,ycor1 Are LINE’s beginning X- and Y-coordinates. 
xcor2 ,ycor2 Are LINE’s ending X- and Y-coordinates. 


color A code indicating the color you want the line 
to be. See the chart earlier in this section for 
color information. 
Examples: 
RUM GF AC ’LINE™. 19237289 
RUN GEXC"LINE™.8,590,192,128) 


RUN - GPxXCMLING 0.0, 1923 126,29 
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Sample Program: 


This procedure draws a sine wave of vertical lines across the 
screen. 


PROCEDURE waves 

UDIM A.B C.D yAs¥ sZt NTEGER 
LICALC=@ \ A=100 

RUN GFXC"mode",@,1) 
RUN GFXC™CLEAR™) 

RUNGE. C'COLOR™ 22 

FOR A2S0 TO 255 STEP 7 
LICALC=CALC+.@5 
LIY=A-SINCCALC)*15 
UZ=Y+25 

IR UNESP CY TNE Xe oh eee 
LINEAL: x 

LIEND 
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MODE Switch to graphics screen 


Syntax: RUN GFX(“MODE”,format,color) 


Function: Switches the screen from alphanumeric (text) to 
graphics, selecting the screen format and color code. You must 
run MODE before you can use any other graphics function. 
When you do, BASICO9 allocates a six-kilobyte block of mem- 
ory for graphics. If your system does not have this amount of 
memory available, OS-9 returns an error message. 


Parameters: 
format Either 0 (a two-color 256 by 192 pixel screen) 
or 1 (a four-color, 128 by 192 pixel screen). 
color A code indicating the color to set the screen. 
See the chart earlier in this chapter for infor- 
mation on color sets. 
Examples: 


RUN GFXC"MODE™,1,2) 
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MOVE Move graphics cursor 


Syntax: RUN GFX(“MOVE”,xcor,ycor) 


Function: Moves the invisible graphics cursor to the specified 
location on the screen. MOVE does not change the display in 
any way. 


Parameters: 


xcor,ycor The coordinates for the cursor. 


Examples: 


RUN GFAC™MDOVE™, 192,128) 


Sample Program: 


This procedure draws and pops bubbles on the screen using the 
CIRCLE function. It uses MOVE to select the position for the 
circles. 


PROCEDURE bubbles 

DIM XCOR; YCOR,T,R,ARRAYC3,1083:INTEGER 
UIRUN: GFX ™MODE™ 1 58 

URUN GFXC"CLEAR") 

POR Pet Te 28 

DARRAYC1,T)=RNDC255) 
JARRAYC2,T)I=RNDC192) 
UARRAYC3,T)=RNDCSG) 

URUN GFXC™MOVE",ARRAYC1,T)I,ARRAYC2,T)) 
URUN GEXAC"CIRCLE™. ARRAY CS, 1343) 

LINEA TE 

UFOR T=1 TO 20 

URUN GFXC™MOVE",ARRAYC1,T),ARRAYC2,T)) 
URUN GFXC™"CIRCLE",ARRAYC3,T),9) 

HSHELL. "“DESPLAY a7" 

UNEXT T 

END 


9-27 


BASICO9 Reference 


POINT Set point to specified color 


Syntax: RUN GFX(“POINT”,xcor,ycor[,color]) 


Function: Displays a dot at the specified coordinates. If you 
specify a color, POINT sets the pixel at the new coordinates to 
that color. Otherwise, POINT sets the pixel at the new coordi- 
nates to the foreground color. 


Parameters: 
xcor,ycor The X- and Y-coordinates for a pixel. 
color The code of the color you want the pixel to be. 
See the chart earlier in this section for color 
information. 
Examples: 


RUM. GEeachPOInT 132.1282 
RUN GFAC™POINI™, 1925128 ,2) 


Sample Program: 
This procedure uses POINT to draw filled boxes on the screen. 


PROCEDURE boxup 

UIDIM XCOR,YCOR,BEGIN,COLOR,QUIT,TERMINATE,LINE: 
INTEGER 

DIM TaXsVYEINTEGER 

UXCOR=58 \YCOR=308 \COLOR=1 

UBEGIN=1 \START=1 \QUIT=28 \TERMINATE=590 
LIRUN GFXC"MODE™. 1499 

RUN -GFKC™CLEAR™? 

UFOR T=1 TO 4 

(IFOR X=BEGIN TO QUIT 

IIFOR Y=START TO TERMINATE 

UIRUN- GFRCPOINT™, *COR+Y.YCOR,COLGR) 
NEXT -¥ 

LIYCOR=YCOR+1 

NEXT X 

USTART=START+19@ 


9-28 


Displaying Text and Graphics / 9 


UTERMINATE=TERMINATE-18 
UCOLOR=COLOR+1 

UNEXT EF 

UINPUT 2$ 

END 
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QUIT Deallocate graphics screen 


Syntax: RUN GFX(“QUIT”) 


Function: Switches the screen to the alphanumeric (text) mode 
and deallocates graphics memory. 


Parameters: None 


Examples: 


RUN GFXC™QUIT") 
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High-Resolution Graphics 


BASIC09’s high-resolution graphics greatly expand the capabili- 
ties of the Color Computer 3. You can have greater screen resolu- 
tion (up to 640 by 192 pixels), as many as 64 colors, and the 
ability to mix graphics and text on one screen. In addition, you 
can use different text fonts, or styles. 


The high-resolution module, GFX2, has many more functions 
than its medium resolution counterpart. GFX2 gives you the 
ability to: 


® Select from 64 colors. OS-9 provides a palette with 16 
default colors. You can change any of these default colors to 
any of the 64 colors available on the Color Computer 3. 


@ Set border colors. 

@ Set color patterns. 

® Create different types of graphics screen cursors. 
@ Use logic functions. 

e Turn an automatic scaling function off or on. 

@ Draw outline or filled boxes. 

@ Draw ellipses and arcs. 

@ Fill specified areas with specified colors. 

@ GET and PUT sections of the graphics screen. 


@ Select character fonts, which include boldfaced, transparent, 
and proportionally spaced characters. 


@ Move the cursor. Erase portions of a line or of the screen. 
@ Select reverse or normal video. 
@ Underline text. 


Also, high-resolution graphics operate through the OS-9 Win- 
dowing System. This means that you can run several procedures 
in different windows. You can establish windows to display text, 
or to display graphics, or both. You can easily display any 
window. 
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Establishing a Hardware Window 


For your convenience, OS-9 has a number of predefined or hard- 
ware window formats. Hardware windows are text windows, and 
you cannot use them for graphic applications. Because hardware 
windows are predefined, you can easily establish them with the 
INIZ command. For instance, to establish Window 7, type: 


iniz w/|ENTER 


However, you cannot see the window until you send a message to 
it. Type: 


echo Hello Window 7 > /w7 [ENTER] 


Now, to see the window and your message press (CLEAR). To 
return to the original screen, press (CLEAR) again. 


To OS-9, a window is a device and you can send data to it. To 
view the Errmsg file in the SYS directory of your system 
diskette, list it to Window 7 by typing: 


list sys/errmsg > /w7 (ENTER] 


Press (CLEAR] to move to Window 7 and see the listing. Press 
SHIFT |(CLEAR] to return to the previous screen. 


You can also fork a shell (an execution environment) to a win- 
dow. To cause a shell to operate in Window 7, type: 


shell i=/w7é 


The i= function of SHELL tells OS-9 that the window is im- 
mortal. It does not die after completing a task. To operate OS-9 
from the window, press (CLEAR }. 


Besides Window 7, you have six other predefined windows. The 
following chart shows all the hardware windows and their 
parameters: 


9-32 


Displaying Text and Graphics / 9 


Starting 

Coordinates 
oa’ Window Screen Size X-Coord, Window Size 
Number Chars/line Y-Coord Cols Rows 
1 40 0,0 27 11 
2 40 28,0 12 jig 
3 40 0,12 40 12 
4 80 0,0 60 Li 
5 80 60,0 19 i 
6 80 0,13 80 12 
7 


80 0,0 80 24 


Defining Windows 


As well as hardware windows, OS-9 also lets you establish win- 
dows to your own specifications. You can set definable windows 
for either text or graphics, or both. You can locate them any- 
where on a screen, and you can make them any size. 


You initialize definable windows in the same manner you initial- 
@) ize hardware windows, using INIZ. If you want to have text on 
the window, you must merge SYS/Stdfonts (found on your system 
diskette) with the window. You can also establish a shell in a 
definable window, from which you can use OS-9 or BASICO9. 


To establish definable windows you must supply OS-9 with infor- 
mation about the type of window you want (its graphic format), 
its size, and its location on the screen. The easiest way to do this 
is with the OS-9 WCREATE command. 
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WCREATE requires a window format code in the form 
- s=format code to tell OS-9 what type of a window you want. 
The following chart shows the possible window formats you can 
choose: 


Table 9.6 
Format Screen Size Resolution No. of | Memory Screen 
Code Cols x Rows Width/Height Colors Required Type 

01 40 x 24 —_—— 167 1600 Text 
02 80 x 24 167 4000 Text 
05 80 x 24 640 x 192 2 16000 Graphics 
06 40 x 24 320 x 192 4 16000 Graphics 
07 80 x 24 640 x 192 4 32000 Graphics 
08 40 x 24 320 x 192 16 32000 Graphics 


00* Specifies the current screen. 
FF Current display screen. Use when putting several windows on the same 
physical screen. 


+ You have to reconfigure the palette to get 16 colors rather than the default of 
eight colors. The following section provides information on the palette. 


Format Codes 01 and 02 select text screens, and Format Codes 5- 
8 select graphics screens. The Screen Size column shows the 
maximum number of text columns and rows available for each 
screen. The Resolution column shows the maximum pixels 
(graphic units) available for each of the graphic screens. The 
Memory column shows how much memory OS-9 must set aside 
for each screen format. Memory requirements depend on the res- 
olution and number of colors selected for a window. 


The Palette 


BASICO9 has 64 colors you can select for screen displays. The 
colors are available through a palette. The Color Computer’s pal- 
ette can hold 16 colors at once. 
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The following chart shows the default colors for the palette in 
Screen Format 7: 


Table 9.7 

Register Color Register Color 
00 Black Black 
01 Red 09 Green 
02 Green 10 Black 
03 Yellow 11 Buff 
04 Blue 12 Black 
05 Magenta 13 Green 
06 Cyan Black 
07 White Orange 


Instead of the default colors, you can select any of the 64 colors 
(0-63) for any of the palette registers. You do this using the PAL- 
ETTE command described later in this chapter. The BORDER 
and COLOR commands also affect the colors available in the pal- 
ette by changing the color in the background and foreground 
registers, Registers 02 and 03, respectively. 


Note: The information in the next section assumes you have 
a Color Computer 3 with 512 kilobytes of memory. If your 
computer has 128 kilobytes of memory, skip to the section 
“High-Level Graphics With 128K.” 


Establishing a Graphics Window 


To create any window, you should first initialize it with the INIZ 
command. Type: 


iniz wl [ENTER | 


So that you can later type in the new window, merge the 
Stdfonts file with it. Type: 


merge sys/stdfonts>/wit 


Using the information in the preceding tables, use WCREATE to 
establish a graphics window. The following command line creates 
a graphics window in Window 1 that has 320 x 192 resolution 
and that fills the entire screen. The new window has 16 colors 
available and provides 40 column by 24 line text: 
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wcreate /w1 -5=8 00 00 40 24 03 02 B2 


ae The screen border color 

| The screen background 
color 
The screen foreground 
color 
The screen length in 
rows 
The screen width in 
columns 
The Y-Coordinate for the 
beginning of the screen 
The X-coordinate for the 
beginning of the screen 
The screen type 
The window name 
The command name 


Starting a Shell in a Window 


At this point, the new window exists, and you can send data to 
it. However, if you want to operate from the window, you must 
install a shell in it. Type: 


shell i=/w1& 
Press to move to the new window. To load BASICO9Y, type: 


basicd9 #10K 


Select either more or less memory, according to your needs. 
Using BASICO9 in a graphics window, you can write procedures 
to create high-resolution graphics, and you can display the 
graphics on the same screen. 
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Using High-Level Graphics With 128K 


If your computer is equipped with only 128 kilobytes of memory, 
you cannot use more than one window with BASICO9. Also, to 
use even one window, you must follow certain steps to provide 
enough memory for BASICO9 operations. 


Refer to Table 9.6. You must select a window mode that does not 
use more than 16000 byte of memory—either window Format 5 
or Format 6. 


To provide enough memory to use BASICO9, you must fork a 
shell to the window you create, then kill the shell in TERM. 
Doing this means that you can no longer operate from your 
TERM screen. However, you can run OS-9 and BASICO9 from 
the window. 


The following steps show you how to create a Format 6 graphics 
screen in Window 1, write a BASICO9 high-resolution graphics 
procedure, and execute it using minimum memory. 


1. Boot OS-9. Then, create a graphics window by typing: 
iniz wt (ENTER] 


wcreate /wi -s=06 00 00 40 24 G6 O1 O1 
merge sys/stdfonts>/w' 

shell i=/w1& [ENTER] 

ex (ENTER) 


2. The system stops, and you can no longer type or issue com- 
mands. Press to move to the new window. Then, load 
BASICO9 by typing: 


basic@9Q [ENTER] 
3. Enter the edit mode, and type the following procedure: 


PROCEDURE squeeze 

UDIM XCOR,YCOR,X,Y: INTEGER; RESPONSE:STRING[1] 
URUN GFX@C"CUROFF'') 

JIXCOR=320 \ YCOR=95 \ X=300 \ FLAG=1 
UPRINT CHRS$C12) 

(LOOP 

UFOR Y=1 TO 198 STEP 2 

UX=X-3 

(IGOSUB 1@ 

LITF FLAG<1 THEN 

IRN: GEX2C" COLOR" .09 
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HELSE 
LIRUN: GF X2C"*COLOR™., 3) 

UENDIF 

IRUN GEXCC™ELLIPSE™, XCOR, YCOR.,% 5 ¥2 
LFLAG=FLAG«-1 

UNEXT -¥ 

RUN GF xet" Color™. 1) 

UIFOR Y¥=99 TG 1 STEP -2 

UGOSUB 18 


UX=X+3 
RUN GF RX2C™ELLIPSE™*,XCOR, YCOR.X%,¥ 
UNEXT Y 

JIRUN. GFxec’ COLOR” .8) 

UENDLOOP 

19@URUN INKEYCRESPONSE) 

LIF KRESPONSES"" TREN 

URETURN 

UENDIF 

19UPRINT CHR$ C12) 

UIRUN GFX2C"COLOR", 6) 

URUN GFX2C"CURON'") 


UEND 


When you have entered the procedure exactly as shown, exit 
the edit mode, and from the BASICO9 command mode, save 
Squeeze by typing: 

Save squeeze 
Compile Squeeze by typing: 

pack squeeze 


Squeeze is now an executable module saved in your current 
execution directory. The following steps assume your execu- 
tion directory is /D0/CMDS. 


Exit BASICO9 by typing: 
bye 


Merge Squeeze, RUNB, INKEY, and GFX2 into one module. 
To do this, type: 


merge /d@/cmds/squeeze /d@/cmds/runb /d@/cmds/ 
inkey gfx2 > /d@/cmds/yawn (ENTER | 


wy 
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8. MERGE does not set the new file Yawn as an executable file. 
Before you execute it, you must make the file executable by 


typing: 
attr /d®@/yawn e pe (ENTER] 


9. To execute Yawn, type: 


yawn (ENTER | 


10. To terminate the procedure, press the space bar. 


The merging procedure in Step 7 saves a considerable amount of 
memory. Every module you load uses one or more 8-kilobyte 
blocks of storage space. For instance, INKEY is only 94 bytes in 
length. However, if you load it as a separate module, it requires 
8192 bytes. RUNB is 12185 bytes in length. This means that it 
requires two 8-kilobyte blocks, or 16384 bytes of memory. GFX2 
is 2190 bytes in length, and Squeeze is 605 bytes in length. 
Loaded individually, they also require two memory blocks. 


If you load all four modules independently, they use 40960 bytes. 
However, by combining them into one file, they load into two 
memory blocks, or 16384 bytes. 


Using the information in this section, you can write and execute 
numerous BASICO9 procedures with only 128 kilobytes of mem- 
ory. However, if your computer has 512 kilobytes of memory, you 
can bypass many of these steps. Also, the additional memory 
enables you to have several windows open at one time. For 
instance, you can create one window in which to write BASICO9 
procedures, another window in which to execute your procedures, 
and a third window from which you can use OS-9 commands. 


Note: The remainder of this chapter assumes you have 512 
kilobytes of memory. If you don’t, you can still run many of 
the sample procedures by implementing the steps in this 
section. 


Creating Windows from BASICO09 


Using GFX2 routines, BASICO9 provides the means to create 
and manage windows. The steps for creating windows from 
BASIC09 are as follows: 


1. DIM a variable to hold the path number to the window you 
want to create. 
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2. OPEN a path to the window. 
3. SELECT the new window as the display window. 


4. Send commands, data, or text to the window through the open 
path. 


5. CLOSE the open path. 
6. Use SELECT to return to your original window. 


If you do not want to return immediately to the screen or win- 
dow of origin, you can skip Steps 5 and 6. 


The following sample procedure shows how to open Window 2 as 
a 320 x 192 graphics window, draw a circle, then return to the 
original screen when you press a key. 


PROCEDURE make__win 

DIM PATH: INTEGER 

DIM RESPENSEsSTERINGL 1 2 

OPEN #PATH,"/We": WRITE 

RUN GFX2 CPATH,"DWSET",08,00,00,40,24,03,02,02) 
RUN GFkS CPATH. "SELECT"? 

RUN GFxS CPATH. “CIRCLE”, 208,98 ,89> 
GET #1.,RESPONSE 

CLOSE #PATH 

RUN GPa. O'SELECT) 

END 


This procedure establishes a Format 8 window, beginning at 
Coordinates 0,0 and covering the total screen. The foreground 
color is green, the background color is black, and the border color 
is black. 


Because this procedure does not INIZ the window it opens, the 
window automatically disappears when the procedure closes its 
path. To create a window that stays in the system, even after 
you close the path to it, use INIZ before the OPEN statement, 
like this: 


SHEGL. “iN swe" 


After you create and define the window, view it by pressing 
(CLEAR }. To get back to the screen you are working on, press 
(CLEAR }. If you intend to use a window more than once in a proce- 
dure, you do not need to close its path until the procedure no 
longer needs it. 
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Creating Overlay Windows 


When you establish a window, you are initializing an OS-9 
device. However, an overlay window is only a new screen for an 
existing window. An overlay screen can be the same size as its 
window, or it can be smaller. OS-9 automatically transfers to the 
overlay window any current procedures operating in the device 
window. 


The process for creating overlay windows lets you select whether 
you want to save the contents of the screen covered by the new 
window. If you choose to save the contents, the previous screen is 
redisplayed when you end the overlay. 


The following procedure provides an example of using overlay 
windows. It creates six overlays, each smaller than the preceding 
window. The procedure then waits for you to press a key. When 
you do, it removes the overlay windows. 


PROCEDURE overwindows 

HDI Aav¥oR lay 1 led Belk PLACE s INTEGER 
UDIM. RESPONSE sSTRINGI 1) 

(X=8 \Y=@ 

“X1=8@ \Y1=24 

UIPLACE=33 

UFOR T=1 TO 6 

HIF T=2 OR T=6 THEN 

JB=3 

VELSE Bee 

BEND LE 

ROS: GF eC OSE Td oh vay ee hg Vo ey 1 
[IX=X+G6 \Y=Yr2 

UX1=X1-12 \Y1=Y1-4 

UFOR J=1 TO 5 

LIPRINT TABCPLACE); “VER ay Se hmem, 23, oF 
NEXT J 

UPLACE=PLACE-6 

i ee ae 

JPRINT “Overlay Screen 6" 

LPRINT “PreSs fi Keys oa" 4 

UIGET #1,RESPONSE 

FOR T=1 TO 6&6 

“RUN GFX2@C"QWEND") 

NEAT OT 

WIEND 
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The Graphics Cursor and the 
Draw Pointer 


High-resolution graphics provide a text cursor, a graphics cursor, 
and a draw pointer. The text cursor and the graphics cursor can 
be either visible or invisible. The draw pointer is always 
invisible. 


Text functions always begin at the current location of the text 
cursor. Whenever you print on the screen, the cursor automati- 
cally moves to the end of the text or to the beginning of the next 
line, depending on whether or not you use a semicolon after the 
print statement. You can reset the text cursor to any place on 
the screen with the CURXY function of GFX2. 


Many BASICO9 graphics functions also begin operating at a 
location pointed to by the draw pointer. When you begin graph- 
ics, the draw pointer is located at coordinates 0,0. BASICO9 then 
updates the pointer as you execute certain graphics functions. 
For instance, the LINE function of GFX2 draws from the draw 
pointer position to the specified end coordinates. The draw 
pointer is left pointing to the end coordinates. 


Because some functions begin at the draw pointer, you need to 
keep track of its location and make certain it is placed properly. 
Use the SETDPTR function to move the draw pointer to new 
locations. 


The graphics cursor is for use with joystick or mouse operations. 
It provides a pointer for graphics applications. The system 
diskette provides patterns that can be loaded into the graphics 
cursor buffer. You can select from a variety of pointer images. 


High-Resolution Text 


When you create a graphics window, you can display either text 
characters, graphics characters, or both. 


To display graphics, move the draw pointer to the location where 
you want the graphics to begin. Then, execute the graphics 
routines. 


To display text, move the text cursor to the location where you 
want the text to begin. Then, use normal BASIC commands to 
print text. 
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Instructions for the draw pointer relate to a 640 x 192 grid, 
numbered 0-639 and 0-191. Instructions for the text cursor 
relate to the number of characters per line and the number of 
lines on the current screen format. 


Using Fonts 


OS-9 has built-in fonts (character sets). You can also create your 
own fonts and instruct BASICO9 to use them. If you create your 
own fonts, you can design any symbols or graphics characters 
you want to use. 


To use fonts, you must be in a graphics window. See “Establish- 
ing a Graphics Screen” earlier in this chapter. Use the FONT 
function to tell OS-9 what font you want. BASICO9 has three 
fonts installed in Group 200, Buffers 1, 2, and 3. The following 
procedure uses characters in Buffer 3 to draw a border, then 
prints a message using the characters in Buffer 2. It then 
returns to Buffer 3 and asks you to press a key to end the 
procedure. 


PROCEDURE borders 

HBiM T2483 Vs0,K2 INTEGER 
UDIM RESPONSE:STRINGL1 1 
UB=199 

UPRINT CHRS$€12) 

LIRUN: GF X!SC™F ONT, 20¢0,3) 
UIRON GF X2C"CELGR”.1 523 
UFOR T=@ TO 79 

UPRINT CHR$CB); 

ONEXT T 

UFOR T=1 TO 21 

LIRUN: GFASC’CURXY™, 8,172 
PRINT CHRSCB)s CHRS(CB); 
RUN GF ACC ™CURKY™ 78.013 
UPRINT CHR$€B); CHR$CB); 
LINEXT T 

UIRUN. GF Z20"CURXY" 8.27) 
UPGR T=% TG 78 

UIPRINT CHRSCB): 

UNEXT T 

URUN GFk2C"FONT™, 200.2) 
RUN GF A2C™CUOLEGR™, 9,29 
RUN GP X2C"CURXY™ 45.92 
UPRINT "A Demonstration" 
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RUN GFXSC™CURXY™ 508.10) 
PRINT “OF A" 

ORUN GFXSC™CURXY™ 43.11) 
UPRINT “Buffer Three Border" 
CRUE “GF KEC™CURKY"™ 51.4 729 
PRINT “And 

PIREEN:- GEX2CeCURKY™, 45.173) 
UPRINT “Buffer Two Text" 
ORUN GFX2C"FONT",200,1) 
DRUN GFX2C"COLOR™ 352) 
LRUN: GFXEC™CURXY™. 33.175) 
UPRINT “Press A Keyes. 0?" 
OGET #1,RESPONSE 

UPRINT CARS C122 


UEND 


High-Resolution Quick Reference 


High-resolution functions are all part of the GFX2 module. You 
call them in a BASICO9 procedure with the following syntax: 


RUN GF ASCI PATA se“ FUNCTION’C PARAMETER, <>) 19 


Path is an optional variable name that tells OS-9 the window in 
which you want the function performed. Function is the high- 
resolution task you want to perform. Parameter is an essential or 
optional value that affects the performance of the function. Dif- 
ferent functions require or permit different numbers of 
parameters. 


The following reference gives a brief description of the high- 
resolution graphics functions. This list is organized by function. 
Following the quick reference is a detailed reference organized 
alphabetically. 
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Window Commands 


Command 


DWSet 


OWSet 


OWEnd 
Select 

DWEnd 
CWArea 


DWProtectSw 


Function 


Establishes a window and sets its location 
on the screen, its size, its background color, 
its foreground color, and its border color. 


Establishes an overlay window on a device 
window that already exists. The function 
also sets the overlay window size, back- 
ground color, foreground color, and border 
color. When using this function, you can 
choose whether or not to save the contents 
of the original screen. 


Deallocates the specified overlay window. 
Selects the window to display. 
Deallocates an established window. 


Changes the size of a window. You can only 
reduce the working area of a window, not 
increase it. 


Lets you unprotect a window and set other 
device windows over it. This might destroy 
the contents of either or both windows. 
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Drawing Commands: 


Command Function 

Point Sets the pixel under the draw pointer to the 
specified color or to the default color. 

Line Draws a line. 

Box Draws a rectangle outline. 

Bar Draws a filled rectangle. 

Circle Draws a circle. 

Ellipse Draws an ellipse. 

Arc Draws an arc. 

Fill Fills the area of the window the same color 


as the pixel under the draw pointer. 


Clear Clears the window. 
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Configuring Commands: 


Command 


Color 


DefCol 
Border 
Palette 


Pattern 
Logic 
GCSet 


ScaleSw 
SetDPtr 
PutGC 


Draw 


Function 


Sets any of the foreground, background, or 
border colors. 


Sets palette registers to the default colors. 
Sets the border palette register. 
Changes colors in the palette registers. 


Establishes a buffer from which BASICO9 
gets a pattern for graphics functions. 


Turns on AND, OR, or XOR logic functions 
for draw functions. 


Establishes a buffer from which BASICO09 
gets the graphics cursor. 


Turns scaling on or off. 
Positions the draw pointer. 
Positions the graphics cursor. 


Draws an image from directions provided in 
a draw string. 


Get/Put Commands: 


Command 


Get 


Put 


DefBuff 
GPLoad 
KillBuff 


Function 


Saves a specified portion of a window to a 
buffer. 


Places the image stored in a buffer onto a 
window. 


Defines a buffer for storage. 
Preloads a buffer from a disk file. 


Deallocates a buffer. 
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Text/Cursor Handling Routines: 


Command Function 

CurHome Positions the cursor at coordinates 0,0. 

CurXY Positions the cursor at_ specified 
coordinates. 

ErLine Erases the line under the cursor. 

ErEOLine Erases from the cursor to the end of the 
line. 

CurOff Turns the graphics cursor off. 

CurOn Turns the graphics cursor on. 

CurRgt Moves the graphics cursor right one space. 

Bell Sounds the terminal bell. 

CurLft Moves the graphics cursor left one space. 

CurUp Moves the graphics cursor up one line. 

CurDwn Moves the graphics cursor down one line. 
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Font Handling Commands: 


Command 


Font 


TCharSw 
BoldSw 
PropSw 
ErEoWndw 


Clear 
CrRtn 


ReVOn 
ReVOff 
UndInOn 
UndInOff 
BlnkOn 


BinkOff 


InsLin 


DelLin 


Function 


Specifies the buffer from which BASICO9 
selects its font characters. 


Selects or deselects transparent characters. 
Selects or deselects bold characters. 
Selects or deselects proportional characters. 


Erases from the graphics cursor to the end 
of the window. 


Erases window and homes the cursor. 


Performs a carriage return by moving the 
cursor down one line and to the extreme left 
of the window. 


Turns reverse video on. 
Turns reverse video off. 
Turns the underline function on. 
Turns the underline function off. 


Turns blinking characters on (only for hard- 
ware text screens). 


Turns blinking characters off (only for hard- 
ware text screens). 


Inserts a blank line at the graphics cursor 
position. 


Deletes the line at the graphics cursor 
position. 
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ARC Draw an arc 


Syntax: RUN GFX2([path,|“ARC”[,mx,my], 
xrad, yrad,xcor1,ycor1,xcor2, ycor2) 


Function: Draws an arc at the current or specified draw posi- 
tion with the specified X and Y radius. If you specify the 
same radius for both X and Y, the function draws a circular 
arc, otherwise the arc is elliptical. The X coordinates are in 
the range 0-639. The Y coordinates are in the range 0-191. 


ARC begins drawing from the point on the screen closest to 
the first set of coordinates (xcorl, ycor1). It stops at the por- 
tion of the screen closest to the second set of coordinates 
(xcor2, ycor2). You can determine on which side of the line 
ARC draws by selecting which set of coordinates is the begin- 
ning and which set is the end. 


Parameters: 


path 
mx,my 
xrad 


yrad 


xcorl ,ycor1 
xcor2 ,ycor2 


Examples: 


The route to the window in which you want to 


draw an arc. 


The X- and Y-coordinates for the center of the 
arc. If you do not specify mx and my, BASICO9 
uses the current draw pointer position. 


The radius of the arc’s width. 
The radius of the arc’s height. 


The beginning and ending coordinates for an 
imaginary line from which the function draws 
an arc. The line is relative to the center of the 
arc (the center point is at 0,0 for these coordi- 
nates) and extends through the two coordi- 
nates from one edge of the screen to the other. 


RUN GFX2C"ARC™, 58,168,509 ,100,30,7598) 
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Sample Program: 


a This procedure draws a series of diagonally-cut arcs on a graph- 
ics window screen. 


PROCEDURE arcing 

ODIM MX,MY,XRAD,YRAD,XCOR,YCOR,XCOR2,YCOR2: INTEGER 
DIM Taoka¥ 22 INTEGER 

UIPRINT CHR$C€12) 

UPOR TS 1a Qe STEP 2 

RUN GFX2C™ARC™.318,95.,1750,159351<9 
LIRUN -GFX2C™ARC’ ,324,95.158,1,1,4851 
LINEXT T 


me 
1) 


? 
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BAR Fill a rectangle 


Syntax: RUN GFX2((path,|“BAR”[,xcorl1, ycor!1],xcor2, 
ycor2) 


Function: Fills a rectangular area defined by two sets of coor- 
dinates. BAR defines its area with an imaginary diagonal 
line from the first set of coordinates to the second set of coor- 
dinates. The X coordinates are in the range 0-639. The Y 
coordinates are in the range 0-191. 


Parameters: 
path The route to the window in which you want to 
draw a bar. 
xcor1 ,ycor1 The beginning coordinates of the line defining 


the area to fill. If you omit these coordinates, 
BAR uses the draw pointer position. See the 
previous section “The Graphics Cursor and 
The Draw Pointer.” Also see SETDPTR. 


xcor2,ycor2 The ending coordinates of the line defining the 
area to fill. 


Examples: 


RUN GFX2C"BAR", 208,100) 


RUN GFX2C"BAR",08,09,100,50) 


Sample Program: 
This procedure draws a bar chart on a window screen. 


PROCEDURE OSgraf 

UDIM COLOR,T,X,XCOR1,YCOR1,XCOR2,YCOR2: 

INTEGERS RESPONSE STRING 11 

LUIPRINT CHR$C€12) 

RUN GFX2C"DEFCOL™) 

-COLOR=13 \ XCOR1=1@ \ YCOR1=189 

JXCOR2=XCOR1+40 

UIRUN GFX2C™"CUROFF"') 
mcmama 
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UFOR T=1 TO 19 

UJREAD YCOR2 

UIRUN GFX2@Cc"COLOR",COLOR) 

URUN GFX2C"BAR", XCOR1,YCOR1,XCOR2,YCOR2) 
UIRUN GF X2c™"COLOGR",7) 

URUN -GEX2C"BOX*, XCOR1 .YCORT,XCOR]. YCORZ) 
JICOLOR=COLOR+1 \ XCOR1=XCOR1+5@ \ XCOR2=XCOR1+49 
NEAT oF 

Peon? \. PRINT © OS-9 Sales Chart" 
URUN GFX2c"BOX",8@,0,510,180) 

UGET #1,RESPONSE 

LIRUN GFX2@C™CURON') 

UPRINT CHR$(12) 

CEND 

-DATA 1780,158,140,130,110,90,70,60,50,39 
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BE LL Ring the terminal bell 


Syntax: RUN GFX2(“BELL”) 


Function: Rings the terminal’s bell (produces a beep through 
the speaker). 


Parameters: None 


Examples: 


RUN: GF X2C"BELL™) 
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BLN KON Character blink on 
BLN KOF F Character blink off 


Syntax: RUN GFX2([path,|“BLNKON’’) 
RUN GFX2([path,]|““BLNKOFF’’) 


Function: Executing BLNKON causes all subsequent charac- 
ters sent to a window on a hardware screen to blink. A hard- 
ware screen is one of the predefined device windows /W1 
through /W7. Executing BLNKOFF cancels a previous blink 
command; characters already blinking continue to do so. Blink 
does not operate on graphics windows. 


Parameters: 
path The route to the window in which you want to 
blink characters. 
Examples: 


RUN GFXeC™BLNKON' 2 


RUN GF ASCVBLNKOPE™) 
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BOLDSW Switch bold characters on or off 


Syntax: RUN GFX2([path,]“BOLDSW”,“switch’) 


Function: Causes characters to display in either regular or 
bold typeface. The default is regular typeface. BOLD only 
works on graphics screens. 


Parameters: 
path The route to the window in which you want 
bold characters. 
switch Can be either “ON” or “OFF.” If switch is 
“ON,” subsequent characters are bold. If 
switch is “OFF,” subsequent characters are 
not bold. 
Examples: 


RUN Grice BELDSHY.“ON"™) 


Sample Program: 


This procedure demonstrates the BOLDSW function by display- 
ing both bold and normal text on a window screen. 


PROCEDURE bold 

UDIM LINE:STRING 

DIM LETTERSSTRINGLE 13 
UDIM: T,35,FLAG? INTEGER 
URUN GFX2@C"CLEAR") 
UFLAG=1 

UFOR T=1 TO 8 

UREAD LINE 

JFOR J*1 TO LENCLINED 
JLETTER=MIDSCLINE «51 


LHe LETTERS AND LET PERS oe “THEN 
PRINT LETTERS 

UENDIF 

Er LETTERS "Sf" oFoeEN 


LIFLAG=FLAGs-1 


ee SE ET SE a A SR SS PT SSE 
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HIF FLAG>@ THEN 

LWIRUN GFXSC"BOLDSWY."OFF*)> 

ELSE 

RUN GFX2eCc"BOLDSW","ON'') 

OENDIF 

ENDIF 

DIF LETTER=""#" THEN 

UPRINT CHR$C€34):; 

UENDIF 

NEXT al 

OPRINT 

ONEXT T 

DOPRINT \ PRINT 

DEND 

UDATA "This is a demonstration of" 
JIDATA "the !Bold! function of" 
UDATA "BASIC09’s GFX2 module." 
UDATA "Use the command" 

UDATA "!RUN GFX2C#BOLDSW4,#0N#)!" 
UDATA "to turn boldface on." 
UDATA "Use !RUN GFX2C#BOLDSWe ,#OFFe)I" 
UDATA “to turn boldface off" 
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BORDER Set the border color 


Syntax: RUN GFX2([path,|“BORDER’”,color) 


Function: Resets the palette register that affects a window’s 
border color (Register 0) to the specified color code. For infor- 
mation on the palette and on screen colors, see “The Palette” 
and Table 9.7 earlier in this chapter. 


Parameters: 
path The route to the window in which you want to 
change border color. 
color One of the current palette colors. Color can be 
either a constant or a variable. 
Examples: 


RUN OP X2C" BORDER”, 72 


Sample Program: 


This procedure lets you select different border colors by 
pressing or (—] to select higher or lower color codes. 
Press (q) to end the procedure. 


PROCEDURE border 

DIM COLOR: INTEGER 

UDIM KEY2:STRINGET I 

LICOLOR=8 

UIRUN GFx2C" CLEAR? 

WHILE KEY<9"™q™" AND KEY<2"Q" DO 
OGET #1,KEY 


OIF KEY="-" OR KEY="=" THEN 
OCOLOR=COLOR-1 

JENDIF 

OIF KEY="+" OR KEY="3;" THEN 
OCOLOR=COLOR+1 

OENDIF 
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DIF COLOR>15 QR COLOR<@ THEN COLOR=8 
UENDIF 

URUN GFX2C"BORDER",COLOR) 

ERUN GFEACC™CURXY” 5. 8.583 

UENDWHILE 

HEND 
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BOX Draw a rectangle 


Syntax: RUN GFX2([path,]“BOX”[,xcorl,ycor1], 
xcor2, ycor2) 


Function: Draws a rectangle. BOX defines its area with an 
imaginary diagonal line from the first set of coordinates to 
the second set of coordinates. BOX does not reset the draw 
pointer. The X coordinates are in the range 0-639. The Y 
coordinates are in the range 0-191. 


Parameters: 
path The route to the window in which you want to 
draw a box. 
xcorl,ycor1 The beginning coordinates for the line that 
defines the rectangle to drawn. If you omit 
these coordinates, BOX uses the draw pointer 
position. 
xcor2,cor2 The ending coordinates for the line that 
defines the rectangular area to be drawn. 
Examples: 


RUN GFX2C"BOX", 200,100) 


RUN GFX2C™BOX" .0,0,1089,58) 


Sample Program: 


This procedure draws a series of progressively smaller boxes of 
different colors on a window screen. Then, it rapidly changes the 
colors of the boxes to produce a hypnotic effect. 


PROCEDURE hypbox 

IDEM As Yak to VI el eRe COULGREINTIEGER 
DIM KEY SSTRINGTT I 

Ley eee 

UX=18 \Y=6 

UY1=18S \X1=621 

URUN GFX2C"CLEAR") 


aera rreeree sre s reese cccccccc  S SSSSSSSSSSSSSSSS 


9-60 


Displaying Text and Graphics / 9 


FOR T=8 TO 1S 

UCOLOR=T 

RUN GFxX2cC"CcoLOR™ ,3) 

UIRUN. GE ASC" BOR 25 95445 12 
URUN GFX2c"COLOR",COLOR) 
RUN: Geeeo Tr TLL cat. yD 
UX=X+18 \Y=Y+G 

UXTSK TTS AY THVT H6 

UNEAT. © 

IWAICE KeEY=""" (DO 

URUN INKEYCKEY) 

UFOR T=1 TO 16 

UR=RNDC65) 

RUN GPxX2C™"PALETTE™,T>R9 
UNEXT T 

UJENDWHILE 

UIRUN: GPX2C™DEFCOL**> 

LEND 
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CIRCLE Draw a circle 


Syntax: RUN GFX2([path,]“CIRCLE”[,xcor,ycor], 
radius) 


Function: Draws a circle with a specified radius. If you specify 
coordinates, CIRCLE uses them for the center point. Other- 
wise, CIRCLE locates the center of the circle at the current 
draw pointer position. See “The Graphics Cursor and the 
Draw Pointer” earlier in this section. Also see SETDPTR. 


Parameters: 
path The route to the window in which you want to 
draw a circle. 
xcor,ycor The coordinates for the circle’s center. The X 
coordinates are in the range 0-639. The Y 
coordinates are in the range 0-191. 
radius The radius of the circle. 
Examples: 


RUN GFX2C"™CIRCLE",100) 


RUN GFX2C"CIRCLE",108,200,50) 
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Sample Program: 
> This procedure uses circles to produce a geometric design. 


PROCEDURE ciraround 
DIM T,45 Ye INTEGER 
LIPRINT CHR$C€12) 

ORUN GP ReEC™COLGR"™, 1.29 
UFOR T=1 TO 130 
UX=158*SINCT)+320 
UY¥=25*COUSCT)+96 

UIRUN: (GF REC™CERCLE™:Xs.¥5 100) 
HNG Aw ob 

URUN GEXSC™COLUR™, 3.2) 

POR T=1 TO 45 
UX=150*SINCT)I+329 
UY¥=25*COSCT)+96 

RUN GFK2CYCIROLE xs YI ee2 
LINE oe 


END 
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CLEAR Clear the screen 


Syntax: RUN GFX2([path,|“CLEAR’’) 


Function: Clears the current working area of a window. 
CLEAR does not change the location of the draw pointer but 
does set the text cursor and graphics cursor location to the 
upper left corner of the window. 


Parameters: 


path The route to the window you want to clear. 


Examples: 


RUN GF X2C"CLEAR™) 
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COLOR Set screen colors 


Syntax: RUN GFX2([path,]“COLOR”, 
foreground|, background], border}) 


Function: Changes any of the foreground, background, or the 
border colors. COLOR does not change the draw pointer 


position. 


Parameters: 


path 
foreground 
background 


border 


Examples: 


The route to the window in which you want to 
change one or more screen or text colors. 


The register number for the foreground 
palette. 


The register number for the background 
palette. 


The register number for the border palette. 
Changing the border color for any window on a 
screen, changes the border color for all win- 
dows on the same screen. 


RUN GFX2C"COLOR",1) 
RUN GAC CULUR™ 1522 
RUM, GF ASCP COLER™ 1,247 2 
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Sample Program: 


This procedure fills a window screen with multicolored filled 
circles. 


PROCEDURE bubbles 

EDIM: X—5¥oW,2,T SiN TeEGeErR 
UZ=1 

DRUM GFA2CVEOCOR’. 1,082 
ORUN GFX2C™"CLEAR") 

UFOR T#=1 TO 88 
UX=RNDC635)+4 
UY=RNDC185)+5 
UW=RNDCS8+5) 

LZ=Z+ 1 

ULF 293 THEN 221 

REND 

RUN GFX2C"CIRCLE™, X,Y ,W) 
RUN GFR2C"COLUR™., 2) 

RUN GPACC VE TEL A 4% 2 


DINE ST TF 
UIRUN -OF Ket" COLOR". 3, 2,22 
END 
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CRRIN Carriage return 


Syntax: RUN GFX2([path,]“CRRTN”) 


Function: Causes BASICO9 to send a carriage return to a 
window. The cursor moves down one line and to the extreme 
left of the window. 


Parameters: 
path The route to the window in which you want a 
carriage return. 
Examples: 


RUN GF F2CVCRETN 2 
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CURDWN Cursor down 


Syntax: RUN GFX2([path,]“CURDWN”’) 


Function: Moves the cursor down one text line. The X-coordi- 
nate, or column position, remains the same. 


Parameters: 
path The route to the window in which you want to 
move the cursor. 
Examples: 


RUN GFX2C"CURDWN") 
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CURHOME Cursor home 


Syntax: RUN GFX2([path,]“CURHOME”’) 


Function: Moves the text cursor to the top left corner of the 


screen. 
Parameters: 
path The route to the window where you want to 
reset the cursor 
Examples: 


RUN GFX2C"CURHOME') 
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CURLFT Move cursor left 


Syntax: RUN GFX2([path,]“CURLFT”’) 


Function: Moves the cursor one character to the left. 


Parameters: 
path The route to the window where you want to 
move the cursor. 
Examples: 


RUN “GF AEC CURLET 2 
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CUROF F Turn off cursor 


Syntax: RUN GFX2([path,]“CUROFF”’) 


Function: Makes the cursor invisible. 


Parameters: 
path The route to the window in which you want to 
turn the cursor off. 
Examples: 


RUN GFX2@C"™CUROFF') 
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CURON Turn on cursor 


Syntax: RUN GFX2([path,]“CURON”) 


Function: Makes the text cursor visible. 


Parameters: 
path The route to the window in which you want to 
turn the cursor on. 
Examples: 


RUN GFX2C"CURON") 
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CURRGT Move cursor right 


Syntax: RUN GFX2(“[path,.|CURRGT”) 


Function: Moves the cursor one character to the right. 


Parameters: 
path The route to the window in which you want to 
move the cursor. 
Examples: 


RUN GFX2C"CURRGT') 
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CURUP Move cursor up 


Syntax: RUN GFX2([path,]“CURUP”) 


Function: Moves the cursor up one line. 


Parameters: 


path The route to the window in which you want to 
move the cursor. 


Examples: 


RUN GFASC™CURUP™ ) 
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CURXY Set cursor position 


Syntax: RUN GFX2([path,|“CURXY”,column,row) 


Function: Moves the cursor to the specified column and row 
position. The column and row coordinates are relative to the 
window’s current character width and depth. 


Parameters: 
path The route to the window in which you want to 
move the cursor. 
column The column (horizontal) position for the 
cursor. 
row The row (vertical) position for the cursor. 
Examples: 


RUN GFX2C™CURXY". 185799 
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CWAREA Change working area 


Syntax: RUN GFX2([path,]“CWAREA”,xcor, ycor,sizex, 
sizey) 


Function: Restricts output in the window to the specified area. 
The new area must be the same or smaller than the previous 
working area. When a window’s working area is changed, 
OS-9 scales graphic and text coordinates and graphic images 
to the new proportions. Text characters remain the same size. 


Parameters: 
path The route to the window in which you want to 
change the working area. 
xcor,ycor The beginning coordinates (the upper left cor- 
ner) for the new working area, relative to the 
original window. The coordinates are based on 
the character column and row size of the origi- 
nal window. 
sizex Designates the number of columns in the new 
working area. 
sizey The number of lines available in the new 
working area. 
Examples: 


RUN GFX2C"CWAREA",180,0,40,10) 
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Sample Program: 


This procedure makes the working area in a window progres- 
sively smaller, filling each area with a different color. It then 
changes the areas’ colors rapidly to produce a hypnotic effect. 


PROCEDURE hypnobox 

UDIM As ¥sX14 715 Fo Rs COLOR: INTEGER 
UDIM KEY:STRINGI11] 

UKEY=""" 

UX=3 \Y=1 

UX1=80-CX+X) \Y1=24-CY+Y) 
FOR T=8 TO 190 

URUN GFX2C’CoLoR™,3,T) 

UIRUN GFX2c™CLEAR") 

UORUN GFX2C"CWAREA™.,X5Y¥sX15V19 
UX=X+3 \Y=Yr1 

UX1=88-CX+X) \Y1=24-CY+Y) 


UNEXT T 
URUN GF xe2C’COULUR™, 3,22 
UWHILE KEY="" DO 


URUN INKEYCKEY) 


UFOR T=1 TO 16 
UR=RNDC65) 

RUN GFX2C™PALETTE™,T RD 
UNEXT T 

UENDWHILE 

RUN GEX2C™DEFCOL**) 


URUN GFX2C"CWAREA",8,8,80,24) 
UEND 
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DE FBUFF Define GET/PUT buffer 


Syntax: RUN GFX2(“DEFBUFF”,group, buffer,size) 


Function: Defines a buffer for GET/PUT operations. 


When you define a buffer, you do so by group number and 
buffer number. Each group you define allocates eight kilobytes 
of memory. The system needs 30 bytes of the block for over- 
head, leaving 8162 bytes free. Within the group, you can allo- 
cate one or more buffers. Select a group number and a buffer 
number as indicated in the following “Parameters” section. 
Use these numbers in future references to the buffer. 


A GET/PUT buffer remains allocated until you use the KILL- 
BUFF function to remove it from your system’s memory. For 
more information on Get/Put buffers, see KILLBUFF, PUT, 
GET, and GPLOAD. 


Parameters: 
group A number you select in the range 1-199. 
buffer A number (in the range 1-255) that you 
assign to the buffer you create. 
size The size of the buffer, in the range of 1 to 
8192 bytes, depending on available memory in 
its group. 
Notes: 


One method of selecting a group number is to use SYSCALL 
and the Get ID (103F OC) system call to obtain your user’s 
process ID number. Then, use this ID number as a group 
number. Using this system for all GET/PUT buffer operations, 
ensures against group number overlapping. See the SYS- 
CALL command for more information. 


Examples: 


RUN GFX2C"™DEFBUFF™,1,5,4809H9) 


9-78 


Displaying Text and Graphics / 9 


DE FC OL Set default colors 


Syntax: RUN GFX2([path,|“DEFCOL’’) 


Function: Sets the palette registers back to their default val- 
ues. The type of monitor you have determines the actual hues. 
See “The Palette” and Table 9.7 earlier in this section. 


Parameters: 
path The route to the window in which you want to 
restore the original palette registers. 
Examples: 


RUN OF ACC" DEF COL”? 
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DE LLIN Delete current line of text 


Syntax: RUN GFX2([path,]“DELLIN”) 


Function: Deletes the line on which the cursor is resting and 
closes the space. DELLIN operates on both text and graphics 
screens. 


Parameters: 
path The route to the window in which you want to 
delete a line. 
Examples: 


RUN GFxX2C™DELLIN"™D 


Sample Program: 


This procedure draws a series of various colored concentric cir- “” 


cles, then produces a lemon shape by removing slices of the circle 
with DELLIN. 


PROCEDURE slice 

UDIM X,Y,R,T,COLOR: INTEGER 
URUN GFX2C™CLEAR"™) 
UCOLOR=8 

UX=328 

LY=96 

LrOR T=165: 10 18 STEP =19 
RUN GFXSC* CIRCLE". X,Y .7T) 
UNEXT T 

FOR T=148 TO 328 STEP 198 
URUN GFX2C™"COLOR™,COLOR) 
UIRUN GFX2C"FILL™,T,96) 
UCOLOR=COLOR+1 

UNEXT T 

URUN GFX2C™"CURXY",@,8) ww 
UFOR T=1 TO 8 

URUN GFX2@C™DELLIN") 


NEXT. T 
LIRUN GF X2¢"COLGR", 3,2) 
UEND 


ee ee ee ee ee 
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- DRAW Draw a polyline figure 


Syntax: RUN GFX2([path,]“DRAW”, option list) 


Function: Draws in the directions specified, and for the dis- 
tances specified, in an option list. The option list is a string of 
characters and numbers. You can separate options with spaces 
or commas. You must include commas between the two coordi- 
nates for the B and U options. 


Parameters: 
path The route to the window in which you want to 
draw. 
option list A string consisting of one or more of the fol- 
lowing options: 
Options: 
Nnum draws north (up) num units. 
Snum draws south (down) num units. 
Enum draws east (right) num units. 
Wnum draws west (left) num units. 
NEnum draws northeast (up and right) num units. 
NWnum draws northwest (up and left) num units. 
SEnum draws southeast (down and right) num units. 
SWnum draws southwest (down and left) num units. 
Aval rotates the draw axis. Possible values are: 
0 = normal 
1 = 90 degrees 
2 = 180 degrees 
3 = 270 degrees 
Uxcor,ycor draws a relative vector to the specified coordi- 
nates. Xcor and ycor are relative to the cur- 
o- rent draw pointer position. The draw pointer 


location does not change. Xcor and ycor must 
be separated by a comma. 
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Bxcor,ycor produces a blank line (moves the cursor but 
does not draw). The xcor and ycor coordinates 
are relative to the current draw pointer loca- 
tion. If you specify relative coordinates located 
offscreen, you cannot see subsequent lines. 


Examples: 


RUN GFX2C™DRAW","N10,610,510,W10") 
Sample Program: 


PROCEDURE drawing 

ODIM T,X%,¥,COLOR: INTEGER 
UCOLOR=9 

RUN GFX2c™CLEAR™) 

FOR T=1 TG 96 STEP 6 

ORUN GFX2c™SETDPTR™,3298 ,96) 
UFOR Y=@ TO 3 
UCOLOR=MODCY,2) 

ORUN GFX2C™"COLOR™, COLOR) 
UFOR X=1 TO 4 

READ DR$ 
ODRS="A"+STRECYI+DRE+STRSCTD 
ORUN GFXeCc™DRAW", DR$) 

UNEXT X 

LINEXT Y 

ORESTORE 

UONEXT T 

ORUN GFXec"COLOR", 3) 

WEND 

DATA SN PEs. BS a 
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DWE ND Device window end 


Syntax: RUN GFX2([path,|“DWEND”) 


Function: Deallocates the device window you initialized with 
DWSET and INIZ. If the window deallocated is the last device 
window on the screen, BASICO9 returns the screen memory to 
the system. DWEND automatically positions you in the next 
device window, a result similar to pressing (CLEAR]. You can 
use this function with DWSET to redefine a device window to 
a different type. 


Parameters: 
path The path number of the window you wish to 
end. Path can be a constant or variable. 
Examples: 


RUN GFX2C"DWEND") 
RUN GFX2CPATH,"DWEND") 
RUN GFX2C€3,"DWEND") 


Sample Program: 


From /TERM, this procedure temporarily opens a path to 
Window 3, displays the new window, draws a design, then 
returns to the /TERM screen and closes the path. 


PROCEDURE decorate 

MIDIM PATH, Ts YtINTEGER 

OPEN #PATH."/ Wa" WRITE 

ORUN GFX2CPATH,"DWSET",7,08,09,88,24,3,2,2) 
RUN GPX2CPATH, “SELECT? 

HY =1 

RUN GFA2CPATH, “COLOUR”, 3,2) 

FOR T=) T6 Tes STEP 3 

LY=Y+1 

ORUN GFX2@CPATH,"ELLIPSE",3298,96,T,Y) 
UNEXT T 

RUN GF XPCPATH, “COLOUR”. 1422 

FOR T2135 70 4 SIEP -6 
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RUN: GF FECPATH, “ELLIPSE” ,320.,936:,T.¥) 
Wie INTC S327 s/s THEN 

LY=#V¥+ 

UENDIF 

UNEXT T 

RUN GFA2ZCT. “SELECT? 
URUN GFX2@CPATH,"DWEND") 
UCLOSE #PATH 


WEND 
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DWPROTSW Device window protect switch 


Syntax: RUN GFX2([path,|“DWPROTSW”,“switch’’) 


Function: Lets you uwnprotect one device window and set other 
device windows on top of it. 


OS-9 on the Color Computer 3 normally uses a protected win- 
dowing system that does not allow window devices to overlap. 
Removing the window protection with DWPROTSW lets one 
device window exist on the same screen area as another win- 
dow device. Because this might destroy the contents of an 
unprotected window, you need to use care with this function. 


Parameters: 
path The route to the window you want to 
unprotect. 
switch Either OFF to turn off protection, or ON to 
turn on protection. The default is ON. 
Examples: 


RUN GFX2C"DWPROTSW", OFF 9) 
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DWSET Device window set 


Syntax: RUN GFX2([path,|“DWSET”,format,xcor,ycor, 
width, length, foreground, background, border) 


Function: Defines a device window. Normally, you first open a 
path to a window, then use DWSET to set the window format, 
location, size, and colors. 


Parameters: 

path The route to the window you are defining. 

format The code for the type of screen you want to 
establish. See Table 9.6 at the beginning of 
this section for the formats available. | 

xcor,ycor The coordinates (character column and row) of 
the upper left corner of the screen you want to 
create. 

width The width (in characters) of the new window. 

length The depth (in lines) of the new window. 

foreground The code for the window’s foreground color. 


background The code for the window’s background color. 


border The code for the window’s border color. 


Examples: 


RUN GPASC"DWSET™ ,06458,109,50519.20512,9) 


Sample Program: 


This procedure opens a path to Window 3, uses DWSET to define 
the new window, displays the new window, and draws a graphic 
lemon shape. It then uses SELECT to return to the /TERM win- 
dow or screen, deallocates Window 3, and closes the path. 
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PROCEDURE lemon 
DIM -PATHs leks ¥ Si NTEGER 
NOPEN #¥PATH,"/W3":WRITE 


URUN. GFASCPATH,“DWSET™,7,8,0,88,24,55,2,2) 
ERUN GFASCPATH, M“SELECT™) 


URUN GPX2CPATH,"COLOR™,@,29 
HPOR rsa) TO: 185 Srer os 
LUY=Y¥+t 

URUN GFXACPATH, "ELLIPSE” .320596.17 4572 
LINEAT. T 

UxXeT 

RUN. GFACCPATH, “COLOR” ,3,¢2 

FOR Te62 10 7 STEP <s 

RUN GFXECPATH, “ELLIPSE”, 328,96.%47 2 
GIF INTCT/33=T/3 THEN 

LIX=X+1 

ENDIF 

UNEXT T 

RUN GP ketls"SELECI™? 

URUN GFX2@CPATH,"DWEND") 


OCLOSE #PATH 
END 
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ELLIPSE Draw an ellipse 


Syntax: RUN GFX2([path,]“ELLIPSE”[,xcor,ycor], 
xrad, yrad) 


Function: Draws an ellipse with the center at the current 
draw pointer position or at the specified X,Y coordinates. The 
X coordinates are in the range 0-639. The Y coordinates are 
in the range 0-191. 


Parameters: 
path The route to the window in which you want to 
draw. 
xcor,ycor The coordinates for the ellipse’s center. If you 


omit these coordinates, ELLIPSE uses the 
current draw pointer position. 


xrad,yrad The radii of the ellipse’s length and height. 


Examples: 
RUN GFX2C"ELLIPSE",100,50) 


RUN GF ACC™ELLIFPSE™,10¢@,7255106.19) 


Sample Program: 


This program uses ELLIPSE to draw a graphic design shaped 
like a Christmas tree decoration. 


PROCEDURE xbulb 

UDIM 7. Yt IRTEGER 

LY =1 

URUN GFX2C"COLOR",3,2) 
URUN GFX2C™"CLEAR") 

FOR T#1. TO 188 STEP <3 
UY=Y+1 

URUN GFASCVELLIPSE™., 329, 96.7,7) 
UNEXT T 

RUN GFEX2C"COLOR™, 152) 
UFOoR T#tS8 TO? STEP =6 


a 
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UISUN. GF RCCPELLIPSE™, 320 -96,75 72 
LP INTCT YS 3261 7S THEN 

UY=Y+1 

UENDIF 

NEAT ff 

IRUN GFx2C"COLOR” 352) 

LEND 
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ERE OLIN E Erase to end of line 


Syntax: RUN GFX2([path,]“EREOLINE”’) 


Function: Deletes the portion of the current line from the cur- 
sor to the right side of the window. 


Parameters: 
path The route to the window in which you want to 
erase a portion of a line. 
Examples: 


RUN GFX2C"EREOLINE") 


Sample Program: 


This procedure uses EREOLINE to produce a series of steps 
down the screen. 


PROCEDURE steps 

DIM Task Ke INTEGER 
RUN. GPx2C’COLGR™ 2,532 
HIRUN GFX2C"CLEAR™) 
UORUN. GFX2¢"CGLOR™ ; 3,29 
FOR T=@ TO 2e 

NJeT*3 

RUN GF X20" CURKY™ 3.457) 
RUN GFX2@C"EREOLINE"™) 
UINEXT -f 
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ERE OW N DW Erase to end of window 


Syntax: RUN GFX2([path,]“EREOWNDW”) 


Function: Deletes all the lines in a window from the line on 
which the cursor is positioned to the bottom of the window. 


Parameters: 
path The route to the window in which you want to 
delete screen contents. 
Examples: 


RUN GFX2C"EREOQWNDW" ) 
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ERLINE Delete current line of text 


Syntax: RUN GFX2([path,]“ERLINE”) 


Function: Deletes the current line (on which the cursor is rest- 
ing) from the window but does not close the space. 


Parameters: 
path The route to the window in which you want to 
remove the contents of a screen line. 
Examples: 


KUN GPXe2C™ERLINE™) 


Sample Program: 


This procedure draws a bull’s-eye design, then slices it 
with the ERLINE function. 


PROCEDURE cut 

UDIM Xs ¥,R> 17, CULORSINTEGER 
UCOLOR=@ 

UX=328 

LIY=96 

URUN GFX2C"CLEAR™) 
UCOLOR=8 

FOR T=185 TO 18 STEP -19 
RUN GPASC CIRCLE 2%. ¥s7) 
UNEXT T 

UFOR T=14@ TO 328 STEP 19 
URUN GFX2¢C"COLOR™,COLOR) 
URUN. GF ACCP ILL’. T., 96) 
UCOLOR=COLOR+1 

NEAL | 

JFOR-TS2. TO 22 STEP 2 
RUN: GrArAecC™CORXY"".8. 71) 


URUN GFX2C"ERLINE') 
UNEXT -T 

UIRUN GFX2C"COLOR",3,2) 
JEND 


i 
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FILL Fun (paint) window 


Syntax: RUN GFX2([path,]“FILL”,[xcor,ycor]) 


Function: Paints an area with the current foreground color. 
Paint fills the portion of the window that is the same color as 
the pixel under the draw pointer. 


Parameters: | 
path | The route to the window in which you want to 
use the FILL function. 
xcor,ycor Are optional X- and Y-coordinates to reposi- 
tion the draw pointer before FILL begins. If 
you omit these coordinates, BASICO9 uses the 
current draw position. 
Examples: 


RUN GFX2C"FILL",100,100) 


Sample Program: 
This procedure draws and fills 100 boxes on a window. 


PROCEDURE colorbox 

DIM A.B84,0,0;,7,COLGR: INTEGER 
LICOLOR=8 

URUN GFX2c"CLEAR") 

UFOR T=1 TO 168 
UA=RNDCS5690) 

UB=RNDC151) 

UC=A+RNDC86 ) 

UD=B+RNDC 48) 
UCOLOR=COLOR+1 

UIRUN GFX2C"COLOR",COLOR)D 
UIRUN GFxec"BOXx",A,8,C,D) 
LIRUN. GF ACC™F ILL™, Ati, BF 12 
UNEXT T 
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F ON T Define font buffer 


Syntax: RUN GFX2((path,|“FONT”,group, buffer) 


Function: Defines a buffer from which BASICO9 gets the char- | 
acter font (style) for the current screen. Use the text/cursor | 
handling functions referenced in this section with the font you 
load. When you merge the Stdfonts file in your SYS directory | 
with a graphics window, you have the choice of three fonts 
from Buffers 1, 2, and 3, located in Group 200. You can also 
create your own fonts. FONT works only on graphics screen. 

See “Using Fonts” earlier in this chapter. 
| 


You must load the font you want to use into the defined buffer 
before using FONT. 


Parameters: 
path The route to the window in which you want to ww 
use an alternate font. 
group The group number of the buffer containing the 
font to use. 
buffer The number of the buffer containing the font 
to use. 
Examples: 


RUN GrAct'" FONT 288.2) 
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GC SET Set graphics cursor 


Syntax: RUN GFX2(“GCSET”,group, buffer) 


Function: Defines a buffer from which BASICO9 gets the 
graphics cursor. This lets you define your own cursor for 
graphics operations. To turn the graphics cursor off, use a 
group Number 0. You must execute this command to display a 
graphics cursor. Before using GCSET, you must merge the 
Stdcur file in the SYS directory to the window. 


Parameters: 


group The group number of the buffer containing the 
cursor image to use. See OS-9 Windowing 
System for information on the group to use. 


buffer The number of the buffer that contains the 
cursor image to use. See OS-9 Windowing 
System for information on the buffer to use. 


Examples: 


RUN GFX2C"GCSET™.1 a2 
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GET Get a block from the window 


Syntax: RUN GFX2([path,]“GET”,group, buffer,xcor, 
ycor,xsize, ysize) 3 


Function: Saves a window area Get/Put buffer. Use PUT to 
replace the image to the window. If you did not previously 
define the buffer, BASICO9 creates it. If you store the window 
data in a predefined buffer, the data must be the same size or 
smaller than the buffer. If not, BASICO9 truncates the data to 
the size of the buffer. (Also see PUT and DEFBUFF.) 


Parameters: 
path The route to the window where you want to 
save an image. 
group The group number of the Get buffer (1-199). 
buffer The Get buffer number (1-255). 
xcor,ycor The X- and Y-coordinates of the upper left cor- 
ner of the window image to save. The X- 
coordinates are in the range 0-639. The Y- 
coordinates are in the range 0-191. 
xsize The horizontal size of the window section to 
save. 
ysize The vertical size of the window section to save. 
Examples: 


RUN OF ASCE. 1 aoe OO e104 159 
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Sample Program: 


This procedure draws a character, loads it into a buffer, then 
repeatedly replaces the character to the window screen using 
PUT. Each new image erases the previous image, giving an 
impression of animation. 


PROCEDURE puttdown 


UDIM 
URUN 
URUN 
URUN 
URUN 
URUN 
URUN 
URUN 
URUN 
LIRUN 
URUN 
URUN 


LF OR 
URUN 
URUN 


URUN 
UEND 


UJ=19 


T,J4 INTEGER 

GF XeC"CLEAR™) 

OP ACE ELLIPSE" Seu 76, ley 
GFACC™CIRCULE™320.,98.,59 

OF Ae C™ COLOR” 72 

OF XZ" E ILE, 320,96) 

GPA2C*" COLOUR” 33 

Grae OC PILL" 320590) 
GFX2C"BAR",305,100,335,104) 
OP ACCVGET" 415154288, 85.50.23) 
Gr Xe OE T6142 1g lok seo? 
GPACOUPUT 71525288, 65) 


L=28 TO Salo STEP 6 


UJ=J+2 


OF AS POT ast ol and 


CER TT 


Gr AeCCYRILLBURP se 7.19 
GFX2C"CURON") 
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GPLOAD Load data into Get/Put buffer 


Syntax: RUN GFX2(“GPLOAD”, group, buffer,format, 
xdim, ydim, size) 


Function: Loads a buffer with image data that PUTBLK can 
use for window displays. If the Get/Put buffer is not created, 
BASICO9 creates it. If it is defined, the size of the data should 
not be larger than the buffer. 


Parameters: 


group 
buffer 
format 
xdim 


ydim 


size 


Examples: 


The group number you select, in the range 1- 
199, to let you group buffers. 


A number in the range 1-255 that you assign 
to the buffer you create. 


The type code of the screen format. (See Table 
9.4.) 


The X (horizontal) dimension of the stored 
block. 


The Y (vertical) dimension of the stored block. 


The size of the buffer in bytes. A buffer size 
can be in the range of 1 to 8 kilobytes, 
depending on available memory. 


RUN GFX2C"DEFBUFF™.1,5,86,1984,58,50809 
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INSLIN Insert line 


Syntax: RUN GFX2([path,]“INSLIN”’) 


Function: Moves the window lines at and below the cursor 
down one line. 


Parameters: 
path The route to the window in which you want a 
blank line. 
Examples: 


RUN GFXSC™INSLIN™)D 


Sample Program: 


This procedure draws a round face on the screen, then uses 
INSLIN and DELLIN to make a mouth appear to move. 


PROCEDURE chomp 

DIM 27s Fx INTEGER 

UDIM. RESPONSE+STRINGL1 1 
JRESPONSESs"™ 

URUN -GFXe2C™CLEAR™) 

HIRUN GFXec™CTRCLE™,328.,96,89) 
URUN GF x2C™COLOR™, 8,2) 

UIRUN: OF X2C"F ITLL". 320,969 

URUN -GFxX2c™COLOR™,2) 

URUN -GFx2C"CTROCLEY.285 88.12) 
URUN Greece VCTRCLE* 355.80 ,12) 
RUN GFXe2C"FILL™, 265,88) 

URUN GF Xe2C" Fr LLL 355.889 

RUN -GEA2CV CLR GLE 4315.96.30 
URUN GR AZO CIRCLE*, 325,96, 3) 
LIRUN- GF A2C™ARC™ 326.925.143.939 51s1412 
OIRUN. GF X2C "COLOR? 3.29 

RUN GFAZCM CIRCLE”. 269,772.39 
URUN: GF K2C™CIRCLE™,359,77,>232 
URUN GFX2C™CURKY™ 590,14) 
UREPEAT 
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URUN GFXec"INSLIN") 
UFOR X=1 TO 109 
UNEXT X 

DRUN GF X2C"DELLIN™) 
URUN INKEYCRESPONSE) 
WONT LL RESPONSE S?**” 
UEND 
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KILLBUFF Deallocate Get/Put buffer 


Syntax: RUN GFX2(“KILLBUFF”, group, buffer) 


Deallocates the indicated Get/Put buffer. You select group and 
buffer numbers when you define a buffer or when you load or 
get a window image. For more information on Get/Put buffers, 
see DEFBUFF, PUT, GET, and GPLOAD. 


Parameters: 
group The group number of the buffer you want to 
deallocate, in the range 1-199. Buffer Group 
Numbers 0 and 200-255 are reserved for OS-9 
system use. 
buffer The number of the buffer to deallocate, in the 
range 1-255. 
Examples: 


RUN. GP ASCK ILLBUPF 2155) 


Sample Program: 


This procedure draws a figure on a window screen, loads it 
into a buffer, then repeatedly places it in new locations on the 
screen. Each new PUT erases the previous image. 


PROCEDURE putdown 
UDIM Ke¥sTsJsINTEGER 
ORUN GFxec™CURDFF™) 

URUN GFxee2C"CLEAR™>} 

URUN -GFEX2C"ELLIPSE™ ,329,96,12 54) 
HRUN GFXe2C"CTROLE™$ 328,598,589 

URUN GF x2cC"COLOR".13 

RUN -GexASC'E PLE", 320.96) 

URUN GF Xec"cCOLER”™,3) 

URUN GFXA2C"FILL™, 328,998) 

RUN GFxX’ft" BAR”, 305,180,335, 1649 
URUN -GEKeC" GET" 1.1. 286>.85.,58,23) 
LRUN GEPACCNGED. yea ts lyo84232 
LIRUN OF XeC" PUT", 1,2,288,85) 
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LUJ=19 

FOR F228 70 S59 STer © 
UJ=J+2 

EIRUN- GFERSCVPUT. 75.14 Fada 
UNEXT T 

RUN GFXSC"KILLBUFE "1473 
URUN GFX2@c"CURON") 

UEND 
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LINE. Draw aline 


Syntax: RUN GFX2([path,|“LINE”[,xcor1,ycor1],xcor2, 
ycor2) 


Function: Draws a line in one of the following ways: 


@ From the current draw pointer to the specified X- and Y- 
coordinates. 


@ From the specified beginning X- and Y-coordinates to 
the specified ending X- and Y-coordinates. 


Parameters: 
path The route to the window in which you want to 
draw a line. 
xcorl1 ,ycor1 The optional beginning X- and Y-coordinates 
for the line. 
xcor2 ,ycor2 The ending X- and Y-coordinates for the line. 
Examples: 


RUN GP XALC™LINE” 192,128) 
SUN CFASC™C INE”, 850; 192,128) 


Sample Program: 


This procedure draws a sine wave of vertical lines across a 
window. 


PROCEDURE waves 

UDIM AsX,¥,;2t INTEGER 
LICALC=9 

UA=100 

URUN GFX2eCc"CLEAR") 
HIRUN GFXec™COLOR™.3,2) 
UFOR X=@ TO 638 STEP 1 
LICALC=CALC+.65 
HY=A-SINCCALC)#15 
UZ=Y¥+25 
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LIRUN: GE ACC" LING Ae Ts Aigee 
UNEXT X 
UEND 
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LO GIC Perform logic function 


Syntax: RUN GFX2(“LOGIC”,“function’”) 


Function: Causes BASICO9 to perform the specified logic func- 
tion on all data bits used by subsequent drawing functions. 
Once set, the logic function remains in effect until you turn 


LOGIC off. 


Parameters: 
function can be one of the following logical functions: 
OFF — no logic 
AND — performs AND logic 
OR — performs OR logic 
XOR  — performs XOR logic 
Examples: 


RUN GF X2C"LOGIC™ "AND" > 
RUN OFX2C™LOGIC™,"XOR") 


Sample Program: 


This procedure uses LOGIC to draw a horizontal bar across a 
background of multicolored vertical bars. Using XOR logic, the 
procedure causes the horizontal bar to change the color of each 
vertical bar. 


PROCEDURE logic 

UDIM A; 2,7T,X%,¥, COLOR: INTEGER 
IRON. -GPA2C"LUGTC™, MOFF™) 
URUN GFX2C"CLEAR") 

UCOLOR=@ 

UFOR T=8 TO. 619 STEP 290 
UCOLOR=COLOR+1 

URUN GFX2c"COLOR",COLOR) 
RUN GFX2C™BAR",T,@,T+20,190) 
NEAT 7 

URUN GFX2@c"COLOR",3,2) 

URUN: OF X2CV LOGIC’ "XOR™) 


ST LEE SSE ER LEST STA SS ATS LT SRD SE BEE TE DOE LEIA III IED EI IE TE AAD NE EE EEE a EEE AE EE EIT OSI II 
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UPOR- Est TH ke 
fIRUN GFX2€"BAR" ,8,88 ,629,1122 
UNEXT 7 

BRUN GFe2C"LUGiIo", "Grr 2 


LEND 
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OWSET Establish an overlay window 


Syntax: RUN GFX2([path,|“OWSET”,save switch,xpos, 
ypos,xsize, ysize, foreground, background) 


Function: Creates an overlay window on a previously existing 
device window. Reconfigures the current device window paths 
to use a new area of the screen as the current device window. 


Parameters: 


path The route to the window in which you want to 
set an overlay. 


save switch Either 0 or 1. A value of 0 tells BASICO9 not 
to save the overlaid area. A value of 1 tells 
BASICO9 to save the overlaid area and restore 
it when the new window closes. 


xpos The character column in which to start the 
new window (upper left corner). 

ypos The character row in which to start the new 
window (upper left corner). 

xsize The width of the new window in characters. 

ysize The depth of the new window in rows. 

foreground The foreground color of the new window. 


background The background color of the new window. 


Examples: 
RUN GFX2C"OWSET", @0,44,10,32,8,00,06) 


Sample Program: 


This procedure creates six progressively smaller overlay win- 
dows, labeling each. It then waits for you to press a key, after 
which it erases all the windows and leaves the original window 
intact. 
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PROCEDURE overwin 

HDEM Xs Yah ta ¥ Us los Be Le PLACEs INTEGER 
[DDIM RESPONSE ?#STRINGC1) 

UxX=8 \Y=@ 

OX1=80 \Y1=24 

UPLACE=33 

UOFOR T=1 TO 6 

GIF Tee OR T=6 THEN 

UB=3 

VELSE B=2 

LIENDIF 

ORUN GrieCV ONSET ot otis PSN ls Ye Bef 2 
OX=X+6G \Y=Yre2 

OX1=X1-12 \Y1=Y1-4 

FOR Jet TE 5 

DPRINT TABCPLACE); “Overlay Screen “; T 
UNEXT J 

LIPLACE=PLACE-6 

UNEXT T 

OPRINT “Press A Key..." 

GET #1 RESPUNSE 

LJFOR T=1 TG 6 

HIRUN GFX2Cc"OQWEND") 

CINEXT. T 

LIEND 
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PALE TTE Set color for palette registers 


Syntax: RUN GFX2((path,]“PALETTE”,register,color) 


Function: Sets palette colors. Lets you install any of the Color 
Computer’s 64 colors in the palette for use with text and 
graphics. 


Parameters: 
path The route to the window where you want to 
change palette colors. 
register The number of the register in which you want 
to install a new color. 
color The code of the new color you want to install. 
Examples: 


SUN GPX2C™"PALETTE" 13,32) 


Sample Program: 


This procedure draws a series of bars and circles, then repeat- 
edly changes their colors using PALETTE. 


PROCEDURE palette 

UDIM T,K,J,X,Y,COLOR: INTEGER 
UDIM RESPONSE:STRING[1] 

URUN GFXeEC™COLOR™,332.2) 
UICOLOR=8 

HIRUN GFX2Cc™CLEAR") 

URUN GFX2C"CUROFF"') 

UFOR Y=@ TO 23 STEP 3 

URUN GFX2Cc"COLOR"™,COLOR) 
UIRUN GFX2C"BAR",@,Y,639,Y+3) 
HICOLOR=COLOR+1 

HIF COLOR=2 THEN 
HUCOLOR=COLOR+1 

LENDIEF 

LINEXT Y 

FOR Y=164 TO 185 STEP 3 
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URUN GFReC"COLOR™, COLOR) 

URUN GF AZLS “BAR, 8.75539, %* 22 

UCOLOR=COLOR+1 ) 
ONEXT ¥ wo 
LICOLOR=@ 

LFOR K=45 70 178 STEP 48 

CUFOR T=109 TO 588 STEP 198 

RUN: GF AZo" COLOR, 32 

RUN GF XEC"CIROLE™, Thy o82 

URUN GFX2c"COLOR",COLOR) 

LIRUN GPeACV PILE”, 7 4K2 

UCOLOR=COLOR+1 

HIF COLOR#=2 THEN 

UCOLOR=COLOR+1 

UENDIF 

UNEXT T 

NEAT 

UREPEAT 

UX=RNDC63) 

UREPEAT 

LY=RNDC16)+1 

UUNTIL Y¥<>2 wo 
LUIRUM “GF XZKka" PALETTE; ¥5X%9 

URUN INKEYCRESPONSE ) 

UUNTiL RESPONSES" 

HRUN GFX2C"DEFCOL") 


URUN GFX2Cc"CURON') 


END 
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P ATTE RN Select pattern buffer 


Syntax: RUN GFX2([path,]“PATTERN”, group, buffer) 


Function: Selects the contents of a preloaded Get/Put buffer as 


a pattern for graphics functions. Although PATTERN can use 
a buffer of any size, it uses a specific number of bytes, depend- 
ing on the screen format in use: 


Color Pattern Bits 
Mode Array Size Per Pel 
02 4 bytes x 8 bytes = 32 bytes 1 
04 8 bytes x 8 bytes = 64 bytes 2 
16 16 bytes x 8 bytes = 128 bytes 4 


The pattern array is a 32 x 8 pel representation of graphics 
memory. It takes the current color mode into consideration to 
define the number of bits per pel and pels per byte. If the 
buffer is larger than the number of bytes required, PATTERN 
ignores the extra bytes. BASICO9 uses the selected pattern 
with all draw commands until you change the pattern or turn 
off the pattern function by specifying a group and buffer num- 
ber of 0. 


Parameters: 
path The route to the window in which you want to 
use a new graphics pattern. 
group The group number of the buffer you want to 
use for a graphics pattern. 
buffer The buffer number that you want to use for a 
graphics pattern. 
Examples: 


RUN GFACC™PATTERN™, 1,323 
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Sample Program: 


This procedure loads the current window data at location 0,0 
into a buffer to use as a draw pattern. It then draws a circle and 
fills the circle with the pattern in the buffer. 


PROCEDURE pattern 

UDIM X.¥5T#LNTEGER 

DRUN “GPASC "OE T*.15795 05,855.59 
URUN GFX2ec"COLOR", 4) 

URUN. GFxeC"CLEAR™D 

HRUN GFEXe2C'CIRCLE™..328.,.96,1988) 
URUN GFX2c"FILL™, 329,96) 
WRUN GER2C”PATIERN = 1412 
LIRUN GFXec™"COLOR", 3) 

LIRUN GFXec"FILL",320 ,96) 
LIRUN GFXeC™"PATTERN",@,90) 
LIEND 
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P OIN fh Mark a point 


Syntax: RUN GFX2([path,]“POINT”[,xcor,ycor]) 


Function: Sets the pixel at the current draw pointer position 
or at the specified coordinates to the current foreground color. 
If you do not specify coordinates, POINT sets the pixel at the 
draw pointer. 


Parameters: 
path The route to the window in which you want to 
turn on the specified pixels. 
xcor,ycor Optional coordinates for the POINT function. 
The X-coordinates are in the range 0-639. The 
Y-coordinates are in the range 0-191. 
Examples: 


RUN GFX2C™POINT"™) 
RUM VFACC PRINT" .192,128) 


Sample Program: 


This procedure uses POINT to produce a swirl design on a win- 
dow screen. 


PROCEDURE point 

UBASE @ 

UDIM X€29),YC20): INTEGER 
LOL: Ta Rods Ke INTEGER 


LIRUN GFX2C"CUROFF'') 
RUN. GPA2C"CLEAR™) 
WFOR T= TO 288 STEP <3 
UJ=J+4 

UFOR R=@ TO 11 
UXCRI=INTCT*#SINC30*R+K))+320 
LYCRI=INTCJU*COSC38*R+K))+96 
UIRUN: GFA2C™ POINT"; XORD, ¥CRII 
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UK=K+1 

UNEXT R 

LINEAL of 

ORUN GFX2C"CURON") 


UEND 


9-114 


Displaying Text and Graphics / 9 


PROPSW Proportional space switch 


Syntax: RUN GFX2([path,|“PROPSW”,“switch’’) 


Function: Enables or disables the automatic proportional spac- 
ing of characters on graphic screens. 


Parameters: 
path The route to the window in which you want to 
use proportional character spacing. 
switch Either OFF to turn proportional spacing off, or 
ON to turn proportional spacing on. The 
default setting of the switch is OFF. 
Examples: 


RUN GFA2C"PROPSW™, "ON" 


Sample Program: 


This procedure produces a demonstration of the BASICO9 propor- 
tional spacing function. 


PROCEDURE proport 
UDIM LINE SS TRING 
TIDIM LETTER?STRINGL 1 3 
HDOM TodeKsFLAGt INTEGER 
HORUN GFX2@c"CLEAR") 
UFLAG=1 

HPOR T=. TH te 
UREAD LINE 

FOR Jd=4+ TO LENCLINED 


DULETTER=MID$CLINE,J,1) 


iP LET TeR<o**!* Anp LETTERS? "Ss"  Laeh 
PRIA LErers 

WENDIF 

CLEP EP TE 2 EN 


UFLAG=FLAG*-1 
HIF FLAG>@ THEN 
DRUN GFX2C"FROPSW" "ORR 2 
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NELSE 

ORUN GFX2C"PROPSW", 
OENDIF 

OENDIF 

OIF LETTER="#" THEN 
OPRINT CHR$(€34); 
OENDIF | 


"WANS 
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UNEXT J | 
LUPRINT | 
UNEXT T 

UPRINT \ PRINT 

LEND 

UDATA "This is a demonstration of" 

UDATA "!Proportional Spacing! using" 

LDATA "BASIC@9’s GFX2 module." 

UDATA "" 

DATA “lThe quick brawn fox jumped..." 

UDATA “The quick brown fox jumped..." 

UDATA 

DATA "Use the command" 

DATA "!RUN GFX2C#PROPSW# , #ON#)E" 

UDATA “to turn proportional spacing on." 

DATA "Use !RUN GFX2C#PROPSW#, #OFF et" 

UDATA “to turn proportional spacing off" 
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P UT Put a saved data block on the window 


Syntax: RUN GFX2([path,]“PUT”,group, buffer, 
xcor,ycor) 


Function: Places the image in the specified Get/Put buffer on 
the window. PUT requires only the group and buffer numbers 
and the window coordinates for the upper left corner of the 
image. The GET function saves the dimensions of the block in 
the buffer. PUT automatically handles window format 
conversion. 


Parameters: 
path The route to the window where you want to 
place a pre-saved image. 
group The group number of the buffer in which to 
save the window data. 
buffer The buffer number in which to save the win- 
dow data. 
xcor,ycor The X- and Y-coordinates of the upper left cor- 
ner of the window position. The X-coordinates 
are in the range 0-639. The Y-coordinates are 
in the range 0-191. 
Examples: 


RUN GPeECVPUT".1,5,1796, 589 
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Sample Program: 


This procedure draws a character, loads it into a buffer, then 
repeatedly replaces the character to the window screen using 
PUT. Each new image erases the previous image, giving an 
impression of animation. 


PROCEDURE putdown 
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UDIM: A>¥4 base NIEGER 

URUN GFX2C"CUROFF') 

URUN GFX2C"CLEAR") 

LIRUS GPRe2C™ELLIPSE™, 328,906,124 4) 
HIRUN: GFXAC" CIRCLE”, s28,98,52 
URUN GFX2c"COLOR",1) 

URGUN GPASC FILL, 328,96) 

URUN OF XSC"COLUR" «32 

URUN GFXe2c"FILL", 328,90) 

URUN GFX2C"BAR",305,1080,335,104) 
URUN GP ACZCYMGET™, 15175268 ,85,58,2e2) 
LIRUN °“GFREC"GE to tyeg hs ty SBe2o? 
RUN GRAS rut 1424 286,85) 
LUJ=10 

LF GR Te2@ 10 S59 STEP G 

LJ=J+2 

RUN Grr PUT etal 4s Taal? 

UNEXT T 

URUN GPAetV RI LE BUR rss 1 ah? 

URUN GFX2c"CURON"') 

UEND 
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PUTGC Put graphics cursor 


Syntax: RUN GFX2([path,]“PUTGC”,xcor,ycor) 


Function: Places and displays the graphics cursor at the speci- 
fied location. Use screen relative coordinates for this function, 
not window relative coordinates. The horizontal range is 
0-639. The vertical range is 0-191. 


Parameters: 
path The route to the window where you want to 
display a graphics cursor. 
xcor,ycor The screen coordinates for the cursor location. 
The X coordinates are in the range 0-639. The 
Y coordinates are in the range 0-191. 
Examples: 


RUN GPxXeC™PRUTGC™,108,5) 


Sample Program: 


This procedure displays the available graphic cursors stored in 
group 202. Before this procedure can work, you must merge the 
Stdptrs file in the SYS directory of your system disk with the 
window you are using. For instance, if your system diskette is in 
Drive /DO, merge Stdptrs with Window 1, by typing: 


merge /d@/sys/stdptrs >» /w' 


PROCEDURE viewcur 

UDIM T,Z22¢ENTEGER 

LIRUN GFXec"CLEAR") 

LIFOR T=1 TO 7 

PIR or RSE" OCSET 282.12 


LIRUN. GFA2C™PUTGC™, 328,96) 
UFOR Z=1 TO 6080 

REA T 2 

UNEXT T 

UIRUN GFX2C"GCSET",@,9) 
END 


9-119 


BASICO09 Reference 


RE VON Reverse video on 
RE VOF F Reverse video off 


Syntax: RUN GFX2([path,]“REVON”) 
RUN GFX2([path,]“REVOFF’’) 


Function: Enables or disables reverse video characters. Once 
set, reverse video remains in effect until you execute the 
reverse video off function. 


Parameters: 
path The route to the window in which you want to 
display reverse characters. 
Examples: 


RUN GFX2C™REVON") 
RUN GFAZC’REVOFF™) 
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SCALESW Enable/disable scaling 


Syntax: RUN GFX2([path,]“SCALESW”,“switch’’) 


Function: Enables or disables scaling when drawing on var- 
iously formatted windows. Scaling in windows is normally on. 
If scaling is off, coordinates are relative to the window origin 
coordinates. Scaling does not affect text. 


Parameters: 
path The route to the window where you want to 
turn scaling off or on. 
switch Either OFF (disable scaling) or ON (enable 
scaling). 
Examples: 


RUN “OF Ae CV SCALESH*. "BFF 2 


Sample Program: 


This procedure runs a routine of drawing a design in overlay 
windows twice. The routine runs once with scaling off and once 
with scaling on. After the first routine pauses, press the space 
bar to see the second demonstration. 


PROCEDURE scale 

UDEM Xie Vek 1a ¥1. 2 fo Byda Rel Zt INTEGER 
DIM RESPUNSEsSTRINGET I 

LIRUN GFX2@Cc"CLEAR") 

LIFOR J=1 TO 2 

DIF J=1 THEN 

URUN GExAAc™SCALESW™..* OFF") 
ELSE 

UIRUN GFrYSC’SCALESN”,"ON"™) 
HENDIF 

UX=@ \Y=@0 \X1=8@ \Y1=24 
(FOR T=1 TO 4 

HIF T=2 OR T=6 THEN 

UB=3 
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DELSE Be=2 

DENDIF 

REN GPeeEC™OWSET ot aka lak 13% 138s TD 
OFOR R=1 TO 35 

UW=48*SINCR) +170 

0Z=25*COSCR)I+45 

UIRUN GEXZE"C I RCLE™ WZ, 38) 

UNEXT R 

OX=X+6 \Y=Y+2 \X1=X1-12 \Y¥1=Y1-4 
PINEALE 

UPRINT “Press A Kéyous™5 

UGET #1.,RESPONSE 

UFOR T=1 TO 4 

URUN GFX2C"OWEND") 
ONEXT T 

OINEXT J 

LEND 
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SE LE CT Select next window 


Syntax: RUN GFX2([path],“SELECT”) 


Function: SELECT causes a window to display if the proce- 
dure is operating in the active window. If the procedure is not 
in the active window, the newly selected window displays 
when you press (CLEAR]. If you do not specify a path, BASICO9 
selects the device using the standard input, standard output, 
and standard error paths, Paths 0, 1, and 2. 


Parameters: 


path The path to the window to select. 


Examples: 
RUN GFX2C"SELECT") 
RUN GFX2C1,"SELECT") 


RUN GFX2CPATH; "SELECT" ) 


Sample Program: 


From /TERM, this procedure temporarily opens a path to 
Window 3, creates the window format, and uses SELECT to dis- 
play the new window. It draws a design, then returns to the 
/TERM screen and closes the path. 


PROCEDURE design 
DDIM PATH, TY: INTEGER 
UGPEN #PATH.“/W3S":WRITE 


URUN OP XSCPATH,"DWSET™,.5,0,0;80,249,;352,29 


URUN GFX2CPATH, "SELECT" ) 


LY = 14 

UeoR T=4 TO 2g8 STEP 3 

yey ey 

Rah GFACCPATO. “ELLIPSE™. 320596. 1572 
AEA oF 


RUN GFACOPATH, “COLOR”, 1,29 
UFUR T#=20¢@ TO 1 STEP -6& 
RUN GPKeECPATH, ELLIPSE", 3285,96.75 72 
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UIF INICT/3)*T73 THEN 
LY=Y¥+1 

UENDIF 

UNEXT T 

UIRON -GrAecl ,MSELECT™ >) 
URUN GFX2CPATH,"™DWEND") 
UCLOSE #PATH 

UEND 
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SETDPTR Set draw pointer 


Syntax: RUN GFX2([path,|“SETDPTR”,xcor,ycor) 


Function: Places the draw pointer at the specified coordinates. 
The draw pointer selects the beginning point of the next 
graphics draw function (such as CIRCLE, LINE, BOX, and so 
on), if you do not supply other coordinates. 


Parameters: 
path The route to the screen where you want to set 
the draw pointer. 
xcor,ycor The screen coordinates for the draw pointer 
location. The X-coordinates are in the range 
0-639. The Y-coordinates are in the range 0- 
191. 
Examples: 


RUN GEXSC™SETDPTR™, 188,59) 


Sample Program: 


This procedure uses coordinates from a DATA statement for set- 
ting the draw pointer to create a series of star shapes. 


PROCEDURE star 

UDIM Xs ¥s 1 okt LRTEGER 

UIPRINT CHRS$CT2) 

FoR v=) To 198 

READ X,Y 

UIRUN GPXY2C™SETDPIR"™, XJ, Y¥ed+J2 
UFOR T=1 TO 5 

UREAD X,Y 

URUN GFASC™LINE™ X40, Y Fd 4d) 
NEXT. T 

OINEXT. J 

UDATA 328,46,448,146,200 ,84,4480,84,208,146,3208,46 
WIEND 
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UNDLNON Underline characters on 
UNDLN OF F Underline characters off , 


Syntax: RUN GFX2([path,|“UNDLNON”) 
RUN GFX2([path,|“UNDLNOFF’”’) 


Function: Enables or disables character underline. After you 
execute UNDLNON, all characters displayed are underlined 
until you execute UNDLNOFF. The default is UNDLNOFF. 


Parameters: 
path The route to the window where you want to 
use underline characters. 
Examples: 
RUN GFX2C™"UNDLNON") ww 


RUN GFX2C™UNDLNOFF") 


9-126 


Chapter 10 


BASIC09 Quick Reference 


This chapter contains a quick reference of all BASICO9 com- 
mands, statements, and functions. It includes commands for pro- 
gramming, editing, and debugging, as well as the Commands 


mode commands. 


The following chart lists all BASICO9 keywords that you can use 


in a procedure. 


Statements and Functions 


Command 


ABS 
ACS 
ADDR 
AND 


ASC 


ASN 
ATN 
BASE 


BYE 
CHAIN 


CHD 
CHRS$ 


CHX 
CLOSE 


COS 


Description 
Returns the absolute value of a number. 
Calculates the arccosine of a number. 


Returns an integer value which is the abso- 
lute memory address of a variable, array, or 
structure in a process’s address space. 


Generates the logical AND of two Boolean 
values. 


Returns the ASCII code of the first charac- 
ter in a string. 


Calculates the arcsine of a number. 
Calculates the arctangent of a number. 


Sets the lowest array or data structure sub- 
script in a procedure to either 0 or 1. 


Ends execution of a procedure and termi- 
nates BASICO9. 


Executes a module, passing arguments if 
appropriate. 


Changes the current data directory. 


Returns the ASCII character represented by 
a specified integer. 


Changes the current execution directory. 


Deallocates the specified path to a file or 
device. 


Calculates the cosine of a number. 
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Command 
CREATE 


DATES$ 
DEG 
DATA 


DELETE 
DIM 


DO 
ELSE 
END 


ENDEXIT 
ENDIF 
ENDLOOP 
ENDWHILE 
EOF 

ERR 


ERROR 

EXITIF/ 
ENDEXIT 

EXP 

FALSE 

FIX 


FLOAT 
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Description 


Opens a path and establishes a new file on 
disk. 


Returns the computer’s current date and 
time. 


Causes BASICO9 to calculate angles in 
degrees. 


Stores data in a procedure to be accessed 
by the READ statement. 


Deletes a file from disk. 


Declares simple variables, arrays or complex 
data structure for size and type. 


See WHILE/DO/ENDWHILE. 
See IF/THEN/ELSE/ENDIF. 


Terminates execution of a procedure. 
Returns to the calling procedure or to 
BASIC09’s command mode. Displays the 
specified text. 


See EXITIF/ENDEXIT. 

See IF/THEN/ELSE/ENDIF. 
See LOOP/ENDLOOP. 

See WHILE/DO/ENDWHILE. 
Tests for the end of a disk file. 


Returns the error code of the most recent 
error. 


Generates the specified error. 


Tests conditions in a loop. The procedure 
exits the loop if the condition is true. 


Calculates e (2.71828183) raised to the 
specified value. 


A Boolean function that always returns 
FALSE. 


Rounds a real number and converts it to an 
integer. 


Converts a byte or integer value to a real 
number. 
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Command 
FOR/NEXT 


GET 


GOSUB/ 
RETURN 


IF/THEN/ELSE/ 
ENDIF 


INKEY 
INPUT 
INT 

Oy) KILL 
LAND 
LEFT$ 


LEN 
LET 
LNOT 


LOG 
LOG10 


LOOP! 
ENDLOOP 


>) Lor 


Description 


Creates a program loop of a specified num- 
ber of repetitions. 


Reads an element or a data structure from 
a binary file or a device. 


Transfers program control to a specified 
subroutine. RETURN sends execution back 
to the calling routine. 


Evaluates an expression and performs an 
operation if the conditions are met. Includ- 
ing ELSE causes an alternate operation if 
the conditions are false. 


Stores the character of a keypress in a 
string variable. 


Causes a procedure to accept input from 
the keyboard or other specified device. 


Returns the largest whole number less than 
or equal to the specified value. 


Unlinks a procedure. (Removes it from 
BASIC09’s directory.) 


Performs a bit-by-bit logical AND on 
two-byte, or integer, values. 


Returns the specified number of characters, 
from the leftmost portion of a string. 


Returns the length of the specified string. 
Assigns a value to a variable. 


Performs a bit-by-bit logical NOT function 
on two-byte, or integer, values. 


Calculates the natural logarithm. 
Calculates a base 10 logarithm. 


Establishes a loop. Use EXITIF and 
ENDEXIT to test the loop and exit when a 
specified condition is true. 


Performs a bit-by-bit logical OR on two- 
byte, or integer, values. 
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Command 
LXOR 


MID$ 


MOD 


NEXT 
NOT 


ON ERROR/ 


GOTO 
ON/GOSUB 


ON/GOTO 


OPEN 
OR 
PARAM 
PAUSE 
PEEK 


PI 
POKE 


POS 
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Description 


Performs a bit-by-bit logical EXCLUSIVE 
OR on two-byte, or integer, values. 


Returns the specified number of characters, 
beginning at the specified position in a 
string. 


Returns the modulus (remainder) of a divi- 
sion operation. 


See FOR/NEXT. 


Returns the logical complement of a Boolean 
value. 


Traps errors and transfers control to the 
specified line number. 


Evaluates an expression. Then, selects from 
a list the line number that is in the posi- 
tion indicated by the result of the expres- 
sion. Procedure execution transfers to the 
selected line. 


Evaluates an expression. Then, selects from 
a list the line number that is in the posi- 
tion indicated by the result of the expres- 
sion. Procedure execute jumps to the 
selected line. 


Opens an I/O path to an existing file or 
device. 


Performs a logical OR on two Boolean 
values. 


Describes the parameters a called proce- 
dure expects from a calling procedure. 


Suspends execution of a procedure, and 
enters the Debug mode. 


Returns the byte value of a memory 
address. 


Represents the constant 3.14159265. 


Stores a byte value at a specified memory 
address. 


Returns the current character position of 
the print buffer. 


Command 
PRINT 


PRINT USING 
PRINT# 
PRINT# USING 


PUT 
RAD 


READ 


REM 


REPEAT/UNTIL 
RESTORE 


RETURN 
RIGHT$ 


RND 


RUN 
SEEK 
SGN 
SHELL 


SIN 
SIZE 


SQ 
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Description 


Sends the specified characters or values to 
the display. 


Sends characters or values to the display, 
using the specified format. 


Sends the specified characters or values to 
the specified path. 


Sends characters or values to the specified 
path using the specified format. 


Writes data to a random access file. 


Causes BASICO9 to calculate angles in 
radians. 


Accesses data from procedure DATA lines or 
from files or devices. 


Indicates that the following characters in a 
procedure line are comments and are not to 
be executed. Also use (* OE, 


Establishes a loop that executes until the 
specified condition is met. 


Restores the DATA pointer to the first data 
item or to a specified line. 


See GOSUB/RETURN. 


Returns the number of characters specified, 
from the rightmost portion of a string. 


Returns a random number from a specified 
range. 


Calls another procedure for execution. 
Changes the file pointer address. 
Determines the sign of a number. 


Calls an OS-9 command or program for 
execution. 


Calculates the sine of a specified value. 


Returns the number of bytes assigned to a 
variable, array, or complex data structure. 


Calculates a value raised to the power of 
two. 
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Command 
SQR/SQRT 


STEP 


STOP 


STR$ 
SUBSTRING 


SYSCALL 
TAB 


TAN 
TRIM$ 


TRON/TROFF 
TRUE 

TYPE 

UNTIL 

USING 

VAL 


WHILE/DO/ 
ENDWHILE 
WRITE 


XOR 
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Description 


Calculates the square root of a positive 
number. 


Sets the size of increment in a FOR/NEXT 
loop. 


Terminates the execution of all procedures 
and returns to the BASICO9 Command 
mode. 


Converts numeric data to string data. 


Returns the starting position of a sequence 
of characters in a string. 


Executes an OS-9 System Call. 


Begins a print operation at the specified 
column. 


Calculates the tangent of a value. 


Strips trailing spaces from the specified 
string. 


Turn the trace mode on and off. 
Returns the Boolean value of TRUE. 
Defines a new data type. 

See REPEAT/UNTIL. 

See PRINT USING. 

Converts a string to an integer. 


Executes a loop as long as a specified condi- 
tion is true. 


Writes data in ASCII format to a file or 
device. 


Performs a logical EXCLUSIVE OR on two 
Boolean values. 
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Commands by Type 


Statements 

BASE 0 DIM 

BASE 1 ELSE 

BYE END 

CHAIN ENDEXIT 
CHD ENDIF 

CHX ENDLOOP 
CLOSE ENDWHILE 
CREATE ERROR 

DATA EXITIF/THEN 
DEG FOR/TO/STEP 


DELETE 


GET 


GOSUB 
GOTO 
IF/THEN 
INPUT 
KILL 

LET 

LOOP 
NEXT 

ON ERROR/GOTO 
ON/GOSUB 
ON/GOTO 


Transcendental Functions 


ACS COS LOG10 
ASN EXP PI 
ATN LOG 

Numeric Functions 
ABS LAND MOD 
FIX LNOT RND 
FLOAT LOR SGN 
INT LXOR 

String Functions 
ASC LEFT$ RIGHTS 
CHR$ LEN STR$ — 
DATE$ MID$ SUB 
INKEY 

Miscellaneous Functions 
ADDR FALSE SIZE 
EOF PEEK TAB 
ERR POS TRUE 


OPEN 
PARAM 
PAUSE 
POKE 
PRINT 
FUE 
RAD 
READ 
REM 
REPEAT 
RESTORE 


SIN 
TAN 


SQ 
SQR 
SQRT 


TRIM$ 
VAL 
STR 


SYSCALL 


RETURN 
RUN 
SEEK 
SHELL 
STOP 
TROFF 
TRON 
Leek 
UNTIL 
WHILE/DO 
WRITE 
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Data Types 


The following list shows the BASICO9 data type you can specify 
when defining a variable. 


Type Function 

BOOLEAN Returns TRUE or FALSE 

BYTE Specifies that a numeric variable is to store 
single-byte values. 

INTEGER Specifies that a numeric variable is to store 
integer (two-byte) values. 

REAL Specifies that a numeric variable is to store 
real (five-byte) values. 

STRING Specifies that a variable is to store ASCII 
characters. 


Types of Access for Files 


You can use the following parameters with the CREATE and 
OPEN commands. Check the individual commands for informa- 
tion on which parameter to use with which command. 


Parameter Function 

DIR Lets BASICO9 access a directory-type file 
for reading. Do not use with UPDATE or 
WRITE. 

EXEC Lets BASICO9 access the current execution 
directory rather than the current data 
directory. 

READ Sets the file access mode for reading. 

WRITE Sets the file access mode for writing. 

UPDATE Sets the file access mode for both reading 


and writing. 
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Command Mode 


The following chart lists the commands available from the 
BASICO9 Commands mode: 


Command 


$ 
BYE or 


CHD 


CHX 
DIR 


EDIT or E 
KILL 
LIST 
LOAD 


MEM 


PACK 


RENAME 
RUN 
SAVE 


Function 


Calls the shell command interpreter to exe- 
cute an OS-9 command. 


Returns you to the OS-9 system or to the 
program that called BASICO9. 


Changes the current data directory. 
Changes the current execution directory. 


Displays the name, size, and variable stor- 
age requirement of each procedure in the 
workspace. 


Enters the procedure editor/compiler mode. 


Removes one or more procedures from the 
workspace. 


Displays a formatted listing of one or more 
procedures. 


Loads all procedures from a file into the 
workspace. 


Displays current workspace size or reserves 
a specified amount of memory for the 
workspace. 


Performs a second compilation and stores 
the resulting file in the execution directory. 


Changes a procedure’s name. 
Causes a procedure to execute. 
Writes one or more procedures to disk. 
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Edit Commands 


The following chart lists the commands available from the Edit 


mode: 


Command 


+num 


+ * 


—num 


— * 


text 
line 
line {ENTER 


c/str1/str2/ 
c*/str1/str2 


r line 
r line num 


s/str 
s*/str 
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Function 
Moves the edit pointer to the next line. 


Moves the edit pointer forward a specified 
number of lines. 


Moves the edit pointer past the last line. 


Moves the edit pointer back a specified 
number of lines. 


Moves the edit pointer to the first line. 


A space followed by text inserts an unnum- 
bered line before the current line. 


Typing a line number with or without text 
following it inserts the line into the 
procedure. 


Moves the edit pointer to the line line. 
Changes the text str1 to the text str2. 
Changes all occurrences of str1 to str2. 
Deletes the current line. 

Deletes all the lines in the procedure. 

Lists the current line. 

Lists all the lines in the current procedure. 
Terminates the edit session. 


Renumbers lines from the first line number, 
in increments of 10. 


Renumbers all numbered lines in incre- 
ments of 10. The first line number is 100. 


Renumbers lines from line in increments of 
10. 


Renumbers lines from line, in increments of 
num. 


Searches for the first occurrences of str. 
Searches for all occurrences of str. 
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Debug Commands 


The following table lists all the Debug commands and what they 


accomplish: 


Command 
$command 


BREAK 


CONT 
DEG/RAD 


LET 
LIST 


PRINT var 
STATE 


STEPnum 


TRON/TROFF 


Function 


Tells BASICO9 to execute the specified OS-9 


command or program. 


Sets a breakpoint at the specified 
procedure. 


Causes procedure execution to continue. 


Selects either degrees or radians as the unit 
of angle measurement for trigonometric 
functions. 


Displays the procedures in the workspace. 


Leaves the Debug mode for the System 
mode. 


Assigns a new value to a variable. 


Displays a source listing of the suspended 
procedure. 


Displays the value of the specified variable. 


Lists the nesting order of all active 
procedures. 


Causes execution of the suspended proce- 
dure in specified increments. 


Turns the trace function on and off. 
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Chapter 11 


BASICO0O9 Command Reference 


BASICO9 is made of keywords (functions and statements) that 
you use, with their parameters, to instruct the computer to per- 
form certain operations. 


This chapter is a complete reference for all of BASICO9’s 
keywords. 


Keyword Format 
The reference to each keyword is organized in this manner: 
@ The keyword. 


e The proper syntax (spelling and form) for using the 
keyword. 3 


e A brief description of the keyword’s purpose or effect. 


e@ Descriptions of any parameters or arguments for the 
keyword. 


@ Notes about special features or requirements of the key- 
word, when appropriate. 


@ One or more examples for using the keyword. 
@ One or more sample procedures. 


This format can vary slightly, depending on the complexity of 
each keyword. For instance, some keywords require parameters 
or arguments, and others do not. Some keywords are self- 
explanatory and do not require a sample procedure. 


The Syntax Line 


The second line in each command or keyword reference is the 
syntax line. This line uses keyword constants and keyword vari- 
ables to show you how to construct a command line. Constants 
are words, numbers, or symbols that you type exactly as they 
appear. Variables are words that only represent the actual 
words, numbers, or symbols that you must supply for the 
command. 


11-1 


BASIC09 Reference 


All variables are italic. When you see an italicized word, you 
know that you must supply some other word, name, symbol, or 
value in place of that word. If a word, symbol, or value is not 
italicized, type it exactly the way it appears in the syntax line. 


The syntax line also uses symbols to help you understand how to 
construct a command line. These symbols are: 


[] Words, names, value, or symbols contained between 
right and left brackets are optional. You can use them 
or not, depending on what you want to accomplish with 
the command. 


. Ellipsis indicates that the last parameter can be 
repeated. 


The following syntax line for DELETE requires only one param- 
eter, the variable pathname. 


DELETE “pethnamne” 


Because pathname is italicized, you know that you must replace 
it with other text—in this case the pathlist to the file you want 
to delete. If you wanted to delete a file named Test from the 
ROOT directory of Drive /D1, this syntax line tells you that you 
must type: 


delete "/d1i/test" 


Other syntax lines are more complex, such as the line for 
CREATE: 


CREATE #path,“pathlisti” Laccess model 
[+access model[t+...] 


This line tells you how to create a path to a file or device. 
Because the number symbol (#) is not italicized, you type it 
after the blank space following the keyword. However, 
path,pathlist, and access mode are all italicized. You must 
replace them with other names or values. 


The access mode variable is contained within brackets. This tells 
you that it is optional. You can include an access mode, or not. If 
you don’t, BASICO9 opens the path in the Update Mode. 


The second access mode shows that the command allows two 
access mode parameters, preceded by a plus symbol. The ellipsis 
show that you can have even more access mode parameters. 
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Other syntax lines show that no parameters are required, such 
as: 


DATE$ 


This command returns the current date. There is nothing it 
requires, and you can do nothing else with it. 


Sample Programs 


The sample programs in this chapter are complete. That is, you 
can type them, run them, and get a result. The procedures let 
you see the syntax and form of a command, as well as showing 
you how it might be used in a program. 


Because the programs are executable, the manual shows unfor- 
matted listings (without relative address, indented control struc- 
tures, and so on). This helps eliminate confusion for you when 
you type the program. You can type it exactly as it appears, exit 
the editor, and run the procedure. 
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ABS Return absolute value 


Syntax: ABS(number) 


Function: Computes the absolute value of number. A number’s 
absolute value is its magnitude without regard to its sign. 
Absolute values are always positive or zero. 


Parameters: 


number Any positive or negative number. 


Examples: 
PRINT ABS(-66) 


X=ABSCY) 


Sample Program: 


The following procedure asks you to type the temperature, and 
makes an appropriate comment. It uses ABS to get the absolute 
value of the temperature. 


PROCEDURE temperature 

DIM FEMPe INTEGER 

OINPUT “What’s the temperature outside? CDegrees 
Pisa Ss Lee 

OIF TEMP<@ THEN 


OPRINT "That’s '; ABSCTEMP); " below 
zero!'({LUBrrrrrrr!" 

JEND 

DENDIF 


DIF TEMP=@ THEN 

PRINT "Zero degrees? That’s mighty cold!” 

HEND 

WENDIF 

OPRINT TEMP; ™" degrees above zero? That’s kind of 
balmy...” 

WIEND 
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ACS Return arccosine 


Syntax: ACS(number) 


Function: Calculates the arccosine of number. Use the DEG or 
RAD commands to tell BASICO9 if number is in degrees or 
radians. If you do not specify degrees or radians, the default 
is radians. 


Parameters: 
number The number for which you want to compute 
the arccosine. 
Examples: 


PRINT ASCC.6561) 


Sample Program: 


The procedure calculates the arccosine of a value you type and 
expresses the result in degrees. 


PROCEDURE arccosine 

UDEG 

UDIM NUM:REAL 

JINPUT “Enter a number between -1 and 1",NUM 
HPRINT “The arecosite of “s NUM: ™” is=<="s3 
ACSCNUM) 

HEND 
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ADDR Return the location of a variable 


Syntax: ADDR(name) 


Function: Returns the absolute location in a process’s address 
space of the variable, array, or data structure assigned to 
name. The address returned is that of the first character in 
the variable. If the variable is numeric, one or more of the 
locations might contain zero. 


For instance, if you use ADDR to obtain the address of an 
integer variable that contains the value 44, the first address 
location (byte) contains 0, and the second location contains 44. 


Parameters: 
name The name of a string, a numeric variable, an 
array, or a data structure. 
Examples: 


This procedure displays the memory address where a variable 
named X resides: 


PRINT ADDRCX) 
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Sample Program: 


> This procedure uses ADDR to tell you the memory location of 
| the variable that stores your keyboard entry. 


PROCEDURE address 

UDIM A: INTEGER 

UTM TESTsSTRING 

WINPUT. “Type. 2: airing of chearacterscys' TEST 
UA=ADDRCTEST) 

PRINT “The string you typed is stored at address 
tt ray 

UPRINT “This is whet 1% eonteing?...™ 

FOR T=A TO A+LENCTEST) 

UPRINT CHRSCPEEKCT 22: 

UNEXT T 


UPRINT 
UEND 
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AND Performs a logical AND operation 


Syntax: operand1 AND operand2 


Function: Performs the logical AND operation on two or more 
values, returning a value of either TRUE or FALSE. 


Parameters: 
operand Can be either numeric or string values. 
operand2 

Examples: 
PRINT A>3 AND B>3 


PRINT AS="YES™" AND B$="YES" 


Sample Program: 


The following program calculates an insurance premium rate 
that is based on the answers to some lifestyle questions. Every 
time you press (Y}, the premium rate goes up. The procedure 
uses AND to increase the rate by two percent if you both smoke 
and drink. 


PROCEDURE policy 

DIM POLICY_VALUE,RATE:REAL 
ODIM SMOKE,DRINK:STRING[1] 
OPOLICY_VALUE=1000000. 


URATE=.001 
UENPUT “Doe you smoke? CY¥/ND...°, SMOKE 
OINPUT "Do you drink? CY/N)...",DRINK 


OIF SMOKE=""Y" AND DRINK#="Y¥" THEN RATE#RATE+. 92 
ELSE 

UIE SMOKE="Y¥" “THEN ‘RATE=KRATE?.81 

UENDIF 

DIF DRINK="Y¥" THEN RATE#RATE+. @1 

ENDIF 

JEN DEE 

UPRONT “Your premium 28 "s KATE*PUL ICY VALUE 
END 
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ASC Returns ASCIT code 


Syntax: ASC(string) 


Function: Returns the ASCII code for the first character of 
string. 


ASC returns the value as a decimal number. If string is null 
(contains no characters) BASICO9 returns Error 67 (Illegal 
Argument). 


Parameters: 


string Any string type variable or constant. 


Examples: 
PRINT ASCC"Hello') 


X = ASCCA$) 


Sample Program: 


The following procedure determines whether the first character 
you enter is a hexadecimal digit. To do this, it gets the ASCII 
value of the character and compares it to the ranges for charac- 
ters between 1 and 0 and A and F. 


PROCEDURE hexcheck 
UDIM A: INTEGER 
UDIM HEXNUM:STRING 


UILOOP 
OINPUT “Enter a hexadecimal value...',HEXNUM 
UJA=ASCCHEXNUM) \ C* GET THE ASCLI. CODE -*) 


DEXITIF A<48 OR A>S7 AND A<GS OR AX7B THEN 
OPRINT “Not a hex number." 

DEND 

DENDEXIT 
PRINT “es” 
HENDLOOP 


UJEND 
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ASN Returns arcsine 


Syntax: ASN(number) 


Function: Calculates the arcsine of number. ASN expresses its 
result in radians unless you specify otherwise (see DEG). 


Parameters: 
number The number for which you want to calculate 
the arcsine. 
Examples: 


PRINT ASCC.6561) 


Sample Program: 


The following program calculates the arcsine of a number you 
enter and expresses the result in degrees. 


PROCEDURE arcsine 


UDIM NUM:REAL 

UDEG 

UINPUT “Enter a number (€-1 to 1) ",NUM 

UPRINT “The arcsine of a ™s NUM; " is---": 
ASNCNUM) 

UEND 
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ATN Returns arctangent 


Syntax: ATN(number) 


Function: Calculates the arctangent of number. 


Parameters: 
number The number for which you want to find the 
arctangent. 
Examples: 


PRINT ASCC.6561) 


Sample Program: 


This procedure calculates arcsine, arccosine, and arctangent for 
a value you enter. 


PSOUCEDURE anglecale 

UIDIM NUM:REAL 

LIDEG 

OINPUT “Enter a number '",NUM 

UPRINT 

He oN 7a APCS Ne 4 Areeosi ne”, "Are tangent” 
LPRINT "Number, "Degreass™, “Degrees” ,;"Degrees” 

LP ROL (ORS ie ero ie oie ee See a eee eee em 
HIF NUM>1 OR NUM<-1 THEN 

HPRINT NUM,"UNDEF","UNDEF',ATNCNUM) 
UPRINT 

WEND 

ENDIF 

UPRINT NUM,ASNCNUM) ,ACSCNUM) ,ATNCNUM) 
UPRINT 

UEND 
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BASE Set array base 


Syntax: BASE 0 
BASE 1 


Function: Sets a procedure’s lowest array or data structure 
index to either 0 or 1. If you want to have the first elements in 
arrays set to 0, you must include BASE @ at the beginning of 
the procedure. 


The BASE statement does not affect string operations such as 
MID$, RIGHT$, and LEFT$. BASICO9 always indexes the 
first character of a string as 1. 


Parameters: 
0 or 1 If you do not indicate a BASE setting in a pro- 
cedure, BASICO9 uses a default of 1. 
Examples: 
BASE @ 


Sample Program: 


This procedure determines how many times RND selects each 
number between 0 and 11 out of 1000 selections. It stores the 
results in an array of 12 elements. Because it specifies BASE 0, 
one of the elements in the array is 0. Whenever the procedure 
picks a random number, it increments the value in the corre- 
sponding array number by one. 


PROCEDURE randomtest 
CIBASE @ (+ set the array base at 0. 
CIDIM RND_ARRAY(12),X,R: INTEGER (* dimension array to hold results. 


CIFOR X=@ TO 11 

LIRND__ARRAY(X)=@ (+ initialize array elements at zero. 
LINEXT X 

CISHELL "TMODE -PAUSE" (+ turn off screen pause. 

CIFOR X=1 TO 1000 


CR=RND(11) (* select random number 1000 times, 


11-12 


BASICO09 Command Reference / 11 


CIRND__ARRAY(R)=RND__ARRAY(R) +1 
(+ add 1 to appropriate element. 


CIPRINT 1001-X (+ count down from 1000 to 1. 
LINEXT X 

CIFOR X= TO 11 

LIPRINT "RND selected "; X; " "+ RND__ARRAY(X); " 

Limes." (#display array 

LINEXT X 

CISHELL "TMODE PAUSE" (* turn scroll lock back on. 
CIEND 
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BYE End procedure, terminate BASIC09 


Syntax: BYE 


Function: Ends execution of a procedure and terminates 
BASICO9. The statement closes any open files, but you lose 
any unsaved procedures or data. 


Use BYE to exit packed programs that you call from OS-9 and 
especially programs that you call from procedure files. 


Parameters: None 


Examples: 


INPUT "Press ENTER to return to the system." 3Z2$ 
BYE 


Sample Program: 


This procedure calculates the payments and interest of a loan. 
When it is through, it exits the procedure and BASICO9 with a 
BYE statement. 


PROCEDURE loan 

UIDIM PRIN,LENG,RATE,MONPAY:REAL 
LIDIM RESPONSE: STRING[1] 

LIREPEAT 

LIPRINT "Amortization Program" 

UINPUT "How much do you want to borrow?...",PRIN 
OINPUT “For how many months?...",LENG 

CKINPUT "At what interest rate?...",RATE 
HIA=RATE/1200 . 

LIB=1-1/€1+A)*LENG 

LIMONPAY=PRIN*A/B 

UIMONPAY=INTCMONPAY*100+.5)/100 

LIPRINT “Monthly payments are...$"; 

UIPRINT USING "R12.2<", MONPAY 

LIPRINT "The total interest to pay is...$"3 

LIPRINT USING "r12.2<", MONPAY*LENG-PRIN 

LIPRINT 

UINPUT "Do another calculation?...',RESPONSE 

LIPRINT 

LIPRINT 

UIUNTIL RESPONSE<>"y" 

LIBYE 

UIEND 

a cate ce a aS 5 
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CHAIN Execute another module 


ras 
Syntax: CHAIN “module [parameters|(...)” 


Function: CHAIN performs an OS-9 chain operation, passing 
module as the name of a program to execute. If you include 
other parameters, CHAIN passes them to the executing mod- 
ule. The module must be programmed to expect parameters of 
the type you provide. 


CHAIN exits BASICO9, unlinks BASICO9, and returns the 
freed memory to OS-9. 


CHAIN can begin execution of any module, not only BASICO9 
modules. It executes the module indirectly through the shell 
in order to take advantage of the shell’s parameter processing. 
This has the side effect of leaving the initiated shells active. 
Programs that repeatedly chain to each other eventually fill 

- memory with waiting shells. To prevent this, use the EX 
option to initialize a shell. 


BASICO9 does not close files that are open when you execute 
CHAIN. However, the OS-9 FORK call passes only the stan- 
dard I/O paths (0, 1, and 2) to a child process. Therefore, if 
you need to pass an open path to another program segment, 
use the EX shell option. 


Parameters: 
module The name of the procedure module you want 
BASICO9 to execute. 
parameters String data passed to the chained module. 
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Examples: 
CHAIN "ex BASIC@S menu" 


CHAIN "BASIC@9 #180k sort C""datafile™", 
"'tempf i letetyt 


CHAIN "DIR /DO" 


CHAIN "Dir; Echo *** Copying Directory #44; ex 
basic@9 copydir" 


Sample Program: 


This procedure chains to two others to display a directory or a 
file. It uses CHAIN to call the procedures. 


PROCEDURE chaining 

LIDIM RESPONSE: BYTE 

LIPRINT USING "S26*","- MENU -" (* print menu title. 

LIPRINT 

DIPRINT "1. List current data directory" (* print menu. 

DPRINT "2. Display a file" 

OPRINT "3. Exit to system" 

LIPRINT 

LIINPUT "Select a function (1-3) ",RESPONSE (+# function you want. 
LION RESPONSE GOTO 100,200,300 (* select appropriate function. 
1BBUCHAIN "EX BASIC@9 dirlook" (* chain to list directory. 
COBUCHAIN "EX BASIC@9 display" (*# chain to list file. 

300LIBYE 


PROCEDURE dirlook 
OREM Lists the specified directory 


LISHELL. “DERY (* execute dir command. 
CICHAIN “EX BASICA9 chaining" (# chain back to calling proc. 
LIEND 


PROCEDURE display 
OREM Lists the specified file. 


UDIM <F-LEEs JOB4S TRING 

INPUT “Path of tile to -displays.<* FILE 

[WOB="LiSt “*FILE 

OSHELL JOB (+ list specified file. 

LICHAIN “EX BASIC@9 chaining" (# chain back to calling proc. 
LIEND 
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CHD Change data directory 
CHX Change execution directory 


Syntax: CHD dirpath 
CHX dirpath 


Function: Changes the current data or execution directory. 


Parameters: 


dirpath An existing data or execution directory. 


Examples: 
CHD "/D1/ACCOUNTS/RECEIVABLE"™ 
CHX "/D1/CMDS" 
CHD: fs 


Sample Program: 


This procedure creates a directory, and makes it the data direc- 
tory. Then, it creates a file in the new directory, exits the new 
directory, and deletes the file and the directory. 


PROCEDURE chdtest 

LIDIM PATH: BYTE 

LISHELL "MAKDIR TEST" (+* create new directory named TEST. 
LICHD "TEST" (+ make TEST the data directory. 


LICREATE #PATH,"Samplefile":WRITE (* create a file in TEST. 
CREM Write data into the new file 

CIWRITE #PATH,"This file is for testing only." 

CIWRITE #PATH,"It will be destroyed when this procedure ends." 


UICLOSE #PATH 


LISHELL "LIST samplefile™ (# list the new file. 

GRD: Sey (+ make the ROOT the data directory, 
PISHELL "DEL TEST/samplefile" (+ delete the file. 

LISHELL “DELDIR TEST" (+ delete the directory. 

DIEND 
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CHRS$ Return ASCII character 


Syntax: CHRS$(code) wd 


Function: Returns the ASCII character for the value of code. 
CHR$ is the inverse of the ASC function, which returns the 
ASCII code for a given character. For a complete listing of 
ASCII codes, see Chapter 9. 


Parameters: 
code The ASCII value for a keyboard character or 
special block graphics character. 
Examples: 


PRINT CHR$C€88) 


Sample Program: 


By increasing by one the ASCII values of characters you type, a | 
the following program creates a secret code. It uses CHR$ to dis- 
play the secret code. 


PROCEDURE secret 

CIDIM TEXT, SECRETLINE:STRING(80] 
UIDIM T,CODECHAR: INTEGER 
LITEXT="" 

LISECRETLINE="" 


LIPRINT "Type a line to code in capital letters..." 

DUINPUT TEXT (+ you type a line. 

CIFOR T=1 TO LENCTEXT) 

LICODECHAR=ASC(MIDSCTEXT,T,1)) (* look at each character in line. 


CIIF CODECHAR=90 THEN (+ is it "2"? Tf yes then 

ICODECHAR=64 (# make it one less than "A", 

LIENDIF 

LIIF CODECHAR=32 THEN (+ is character a space? If yes then 

CICODECHAR=31 (+ decrease its value by one. 

MENDIF Lg 
PISECRETLINE=SECRETLINE+CHRS(CODECHAR+1) (# add 1 to characters. 

CINEXT T 

DIPRINT SECRETLINE (+ print the secret code. 

LIEND 


enn nnn nnn nnn nnn nnn nnnncnnnnececrecceeeeeeeeeeeeereeeeeeeeeeee cee SSS 
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CHX Change execution directory 
CHD Change data directory 


Syntax: CHX dirpath 
CHD dirpath 


Function: Changes the current execution or data directory. 


Parameters: 


dirpath An existing execution or data directory. 


Examples: 
CHX "/D1/CMDS" 
CHD "/D1/ACCOUNTS/RECEIVABLE" 
CHE st. 3™ 
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CLOSE Deallocate file or device path 


Syntax: CLOSE #pathnum 


Function: Deallocates the file or device path specified by 
pathnum. 


When you OPEN or CREATE a file, BASICO9 allocates a path 
number to the variable you supply in the OPEN or CREATE 
command. The system then knows the path by that number. If 
the path you CLOSE is to a non-shareable device (such as a 
printer), the system releases the device for other use. Do not 
close paths 0, 1, and 2 (the standard I/O paths) unless you 
immediately open a new path to take over the standard path 
number. 


Parameters: 
pathnum The name of variable containing the path 
number or the actual number of the path to a 
file or device. 
Examples: 


CLOSE #FILEPATH, #PRINTERPATH, #TERMPATH 

CLOSE #5, #6, #7 

CLOSE #1 \ (* closes the standard output path *) 

OPEN #PATH,"/T1" \ (# redirects standard output *) 
Sample Program: 


This procedure creates a directory named TEST and changes it 
to the data directory. It then creates a file named Samplefile and 
writes data to the file. Finally it changes back to the parent 
directory and deletes Samplefile and TEST. 
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PROCEDURE close 
LIDIM PATH: BYTE 
LISHELL "MAKDIR TEST" 


GERD FEST" 
LICREATE #PATH,"samplefile":WRITE (* create a new file. 

LINRITE #PATH,"This file is for testing only." 

CIWRITE #PATH, "It will be destroyed when this procedure ends." 
LICLOSE #PATH (# close the file. 

LISHELL "LIST samplefile™ 

PC aa 
LISHELL: “DELDIR TEST" 
LIEND 
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COS Return cosine 


Syntax: COS(number) 


Function: Calculates the cosine of number. Unless you specify 
DEG, COS interprets the value of number in radians. 


Parameters: 
number The number for which you want to find the 
cosine. 
Examples: 


PRINT COSC45) 


Sample Program: 


This procedure calculates sine, cosine, and tangent of a value 
you enter. 


PROCEDURE ratiocalc 


UDIM NUM:REAL 

LIDEG 

HINPUT "Enter a@ némber... "NUM 

UPRINT 

UPRENT “Namber“SINE’."“COSTNE™." TAN" 

LIPRINT "<<-<9 2-329 <2 ene ee ee eee eee eee eee rece es 


UPRINT ANGLE,SINCNUM) ,COSCNUM) , TANCNUM) 
UPRINT 
UEND 
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CREATE Establish a disk file. 


cr» 

Syntax: 

CREATE # path,“ pathlist’ [access mode] 

[+ access mode][ +...] 

Function: Creates a file on a disk. When you create a file, you 
can select one or more of the following access modes for the 
file: 

Mode Function 

READ Lets you read (receive) data from a file but 

does not let you write (send) data to the file. 

WRITE Lets you write data to a file but does not let 

you read data from a file. 

UPDATE Lets you both read from and write to a file. 

a 

Parameters: 
path The name of the variable in which BASICO9 

stores the number of the opened path. 

pathlist The route to the file or device to be opened, 

including the filename, if appropriate. 

access mode ‘The type of access to be allowed for the file or 

device. Use plus symbols to allow more than 
one type of access with a single file. 

Notes: 

@ You can access files either sequentially or randomly. With 
random access, you must establish the filing system you 
want for a particular application. 

~~ @ Files are byte-addressed, and you are not restricted by 


explicit record lengths. You can read the data one byte at a 
time, or in whatever size portions you want. 
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e A new file has a size of zero. OS-9 then expands the file 
automatically when PRINT, WRITE, or PUT statements 
write beyond the current end-of-file. 


Examples: 
CREATE #TRANS,"transportation":UPDATE 
CREATE #SPOOL,"/user4/report™: WRITE 


CREATE #OUTPATH,name$:UPDATE+EXEC 


Sample Program: 


This procedure CREATEs a directory named TEST and makes it 
the data directory. It creates a file in TEST named Samplefile, 
writes data to the file, then resets the parent directory as the 
data directory. Finally, it deletes Samplefile and TEST. 


PROCEDURE close 

CIDIM PATH:BYTE 

LISHELL "MAKDIR TEST" 

LICHD “TEST 

CICREATE #PATH,"samplefile":WRITE (* create a file. 
CWRITE #PATH,"This file is for testing purposes only." 
CWRITE #PATH,"It will be destroyed when this procedure ends." 
CICLOSE #PATH (# close the file. 

CISHELL "LIST samplefile™ 

CGH ge 

LISHELL "DELDIR TEST" 

LIEND 
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DATA Store numeric and string information 


Syntax: DATA “item”|[,“item’’,...] 


Function: Stores numeric and string constants to be accessed 
by a READ statement. A DATA line can contain up to 254 
characters. Each item in the list must be separated by 
commas. 


You can place DATA statements anywhere in a procedure that 
is convenient. BASICO9 reads sequentially, starting with the 
first item in the first DATA statement, and ending with the 
last item in the last DATA statement. 


The following rules apply to data items: 
@ You must place all string data between quotation marks. 


@ To include quotes in string-type data, use consecutive 
-_ quotation marks, like this: DATA "He said, ""go 
rome" “Lo me . 


@ You can use RESTORE to reset the data pointer. Using 
RESTORE without an argument resets the pointer to the 
beginning of the data items. Using RESTORE with a 
line number, resets the pointer to the first item in the 
specified line. 


@ The READ statement can support a list of one or more 
variable names of various types. The data types in DATA 
statements must match the variable types used in the 
corresponding READ statements. 


@ You can include arithmetic expressions in data items. 
READ causes the expressions to be evaluated and 
returns the result of the expression as the data item. 


Parameters: 
co” 


item Numeric or string characters. Enclose string 
characters in quotation marks. 
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Examples: 
DATA 1.1,1.5,9999,"CAT", "DOG" 
DATA SINCTEMP/25), COSCTEMP*PI) 
DATA TRUE,FALSE,TRUE,TRUE,FALSE 


DATA “The rain in spain’, "Ttalls mainly on the 
plain 


Sample Program: 


This procedure calculates the day of the week for a date you 


enter. A data statement contains the names of the weekdays. 


PROCEDURE weekday 
UDIM X,DAY,MONTH,YEAR,CALC: INTEGER 


INTEGER 
ODIM WEEKDAYC7):STRING[9] 

DPRINT USING “S60*", “Day of the Week Program” 
PRINT. USING *S60*™. "Por eny year atier T7se” 


UPRINT 


as 98...",DAY 

INPUT “Enter month as two digits, such «as 
Loewe ORT A 

LIAPUT “Enter year as Tour digits, siten 4s 
TBS S suas VER 

LUFOR 421 TO 7 

UREAD WEEKDAYCX) 

LINEXT xX 

DANUM=INTC.6+1/MONTH) 
UBNUM=YEAR-ANUM 
LICNUM=MONTH+12*ANUM 
UIDNUM=BNUM/1 09 
UENUM=INTCDNUM/ 4) 
UFNUM=INTCDNUM) 
NIGNUM=INTC5*BNUM/ 4) 
UHNUM=INTC13*CCNUM+1)/5) 

UC INUM=HNUM+GNUM-FNUM+ENUM+DAY -1 
UINUM=INUM-7* INTCINUM/7)+1 


UIPRINT 

UPRINT. *The day of ‘the week on "3. DAY: "7" MONTHS 
UPRENT “/"*s. YEARS ™- aeun oe WEEKDAYCINUMD 

JDATA "Sunday", "Monday", "Tuesday", "Wednesday", 
“Thwesdeay' 

UDATA “Friday”; “Saturday” 

HEND 
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DATES$ Provide date and time 


oe” 
Syntax: DATE$ 


Function: Returns the date and time. The OS-9 internal date 
is kept in the format: 


year/month/day hour:minutes:seconds 


If your OS-9 Startup file contains the SETIME command, the 
system asks you to enter the date and time whenever it boots. 
If it does not contain the SETIME command, the date and 
time start from 86/09/01:00:00:00. 


You can use the normal string functions to access the data 
contained in DATE$, but you cannot use functions or opera- 
tions that attempt to change or append to its values. To reset 
the date or time or both, use the SHELL command, such as: 


- SHELL "SETIME" 
Parameters: None 


Examples: 


PRINT DATE$ 


Sample Program: 


This program is essentially the same as the sample program for 
the DATA statement, except that it gets the day, month, and 
year from DATES. 


PROCEDURE date 

LIDIM X,DAY,MONTH, YEAR, CALC: INTEGER 

LIDIM ANUM,BNUM,CNUM,DNUM,ENUM,FNUM,GNUM,HNUM, INUM: INTEGER 
LIDIM WEEKDAY(7):STRING(9] 

a LIMONTH=VALCMIDSCDATE$ ,4,2)) (* get month from DATES. 
LIDAY=VAL(MIDSCDATE$,7,2)) (# get day from DATES, 
LYEAR=VALC"19"+LEFTS(DATE$ ,2)) (+ get year from DATES. 


LIFOR X=1 707 
UREAD WEEKDAY(X) 
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LINEXT X 
DIANUM=INTC.6+1/MONTH) 
LIBNUM=YEAR-ANUM 
LICNUM=MONTH+12#ANUM 
LIDNUM=BNUM/ 1 08 
DENUM=INTCDNUM/4) 
LIFNUM=INTCDNUM) 
LIGNUM=INT(S#BNUM/4) 
CHNUM=INTC13*(CNUM+1)/5) 
OINUM=HNUM+GNUM-FNUM+ENUM+DAY -1 
CINUM=INUM-7*#INTCINUM/7)+1 
LIPRINT 

DIPRINT "Today is "; WEEKDAYCINUM) 


LIDATA "Sunday","Monday", "Tuesday", "Wednesday", "Thursday", "Friday" 
LIDATA "Saturday" 
LIEND 
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DEG Return trigonometric calculations in 


degrees 


Syntax: DEG 


Function: Causes a procedure to calculate trigonometric val- 


ues in degrees. If you do not include the DEG statement, pro- 
cedures produce radian values. 


Parameters: None 


Examples: 


DEG 


Sample Program: 


This procedure calculates the sine, cosine, and tangent for a 
value you enter. Because it uses the DEG statement, it displays 
the results in degrees. 


PROCEDURE degcalec 


UDIM NUM:REAL 

ODEG 

UINPUT “Enter a number...',NUM 

UP RINT 

UPRINT “Number”. “SINE. "COSINE," TAN® 

OPRINT toro reev eee ee ecees eco oun eeeesedes 


JPRINT NUM,SINCNUM) ,COSCNUM) , TANCNUM) 
UPRINT 
UEND 
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DE LETE Erase a disk file 


Syntax: DELETE “pathname” 


Function: DELETE removes a file from disk storage and 
releases the portion of the disk on which it resides. When you 
DELETE a file, it is permanently lost. 


Parameters: 
pathname The complete pathlist to the file you want to 
delete, including the drive and one or more 
directories, if appropriate. You must surround 
the pathlist with quotation marks. 
Examples: 


DELETE “ryt iie” 


DELETE. "/D1/ACCOUNTS/receivables” 


Sample Program: 


This procedure creates a file named Samplefile, writes data to 
the file, then closes it. It then lists the file before deleting it. 


PROCEDURE close 

DDIM PATH: BYTE 

CICREATE #PATH,"samplefile":WRITE (+* create a file. 

CWRITE #PATH,"This file is for testing purposes only." 
DWRITE #PATH,"It will be destroyed when this procedure ends," 
LICLOSE #PATH (# close the file. 

LISHELL "LIST samplefile™ 

KIDELETE "samplefile" 

LIEND 
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DIM Assign variable storage 


Syntax: DIM variablel....][:typell;variablelf,...]I: typell...] 


Function: Assigns storage space and declares types for vari- 
ables, arrays, or complex data structures. 


Parameters: 
variable A simple variable, an array structure, or a 
complex data structure. 
type BYTE, INTEGER, REAL, BOOLEAN, 
STRING, or user defined. 
Notes: 


@ You declare simple arrays with DIM by using the variable 
name, without a subscript. If you do not explicitly declare 
variables, the system makes them type real unless they are 
followed by a dollar sign ($). The system dimensions vari- 
ables ending with a dollar sign ($) as strings, with a length 
of 32 bytes. You must declare types of all other simple vari- 
ables as to type. 


@ You can declare several variables of the same type by sepa- 
rating them with commas. To separate variables of differ- 
ent types, follow each type group with a colon, the type 
name, and then a semicolon. 


@ Define a maximum length for a string variable by enclosing 
the length in brackets following the type, like this: 


DIM namesstringl2s] 
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If you do not define a maximum length, BASICO9 uses a 
default length of 32 characters. You can declare a shorter 
length or a longer length, up to the capacity of BASICO9’s 
memory. If you try to extend a string beyond its declared 
length, or beyond the default length, the system ignores all 
extra characters. Thus the following: 


DIM name:string[10] 
name = "Abbernathinsky" 


produces the string: 


Abbernathi 

e Arrays can have one, two, or three dimensions. The DIM 
format for dimensioned arrays is the same as for simple 
variables, except that you must follow each array name 
with a subscript, enclosed in parentheses, to indicate its 
size. The maximum array size is 32767. 
Arrays can be either of the standard BASICO9 type or of a 
user-defined type. For information on creating your own 
types for simple variables, arrays, and complex data struc- 
tures, see TYPE. 

Examples: 

DIM logical:BOOLEAN 

DIM 84. bate INTEGER 

DIM name,address,zip:STRING 

DIM name:STRINGL25]; address:STRING( 30]; 

Zioe INTEGER 

DIM no1,n02,n03:REAL;n04,n05,n06: INTEGER; 

nmo7sBYTE 
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Sample Program: 


This procedure randomly selects letters and vowels to create six- 
letter words that might look like alien names. It first DIMs nine 
string variables to contain the letters selected for each name. It 
DIMs two integer variables to provide a loop counter and to store 
the number of names you request. 


When asked, type the number of names you want to have the 
procedure generate. 


PROCEDURE alien 

UDIM B,BEGIN,F,FINISH: STRING 
UDIM VOWELS ,VOWEL1 ,VOWEL2:STRING 
UDIM MID1,MID2:STRING 

UDIM T,RESPONSE: INTEGER 
LIIVOWELS=""aeiouy™ 


UINPUT "How many alien names do you want to 
see?...™", RESPONSE 
UBEGIN="ABCDFGHJKLMNPRSTVWXZ" 

UF INISH="ehimnprstvwyz" 


FOR T=1 TO RESPONSE 
UB=MID$CBEGIN,RNDC19)+1,1) 

UF =MID$CFINISH,RNDC12)+1,1) 
UMID1=CHR$CRNDC25)+97) 
UMID2=CHR$CRNDC25)+97) 
UVOWEL1=MID$CVOWELS,RNDC5)+1,1) 
UVOWEL2=MID$CVOWELS ,RNDC5)+1,1) 

UPRINT B; VOWEL1; MID1; MID2; VOWEL2; F, 
FINEST F 


UPRINT 
END 
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DO Execute procedure lines in a loop 


Syntax: WHILE expression DO 
proclines 
ENDWHILE 


Function: Establishes a loop that executes the procedure lines 
between DO and ENDWHILE as long as the result of the 
expression following WHILE is true. Because the loop is 
tested at the top, the lines within the loop are never executed 
unless expression is true. 


Parameters: 
expression A Boolean expression (produces a result of 
True or False). 
proclines Are program lines to execute if the expression 


is true. 


See WHILE/DO/ENDWHILE for more information. 
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ELSE Execute alternate action 


Syntax: IF condition THEN 
action 
ELSE 
secondary action 
ENDIF 


Function: ELSE provides access to a secondary action within 
an IF/THEN test. When the condition tested by IF is not 
true, BASICO9 executes the secondary action preceded by 
ELSE. 


Parameters: 

condition A Boolean expression (produces a result of 
True or False). 

action A line number to which the procedure is to 
transfer execution, or a program statement. If 
action is a line number, do not include the 
ENDIF statement in the IF test. 

secondary One or more program statements. 

action 


For more information, see IF/THEN/ELSE 
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END Terminate a procedure 


Syntax: END [“text’] 


Function: Ends procedure execution and returns to the calling 
procedure, or to the highest level procedure. If you provide 
output text for END, it functions in the same manner as 
PRINT. You can use END several times in the same proce- 
dure. END is not required as the last statement in a 
procedure. 


Parameters: 


text A literal string or a string-type variable. 


Examples: 
END "Program Terminated" 


LAST$="Session over" 
END LAST$ 


Sample Program: 


This procedure calculates a loan’s term, using END to termi- 
nate routines. 


PROCEDURE loaner 
ODIM YOUPAY,PRINCIPLE, INTEREST ,NUMPAY, YEARS, 


MONTHS:REAL 
ODIM. RESPONSE:STRING( 13 


OREPEAT 

UPRINT 

OPRINT USING "S45%","Loan Terms" 

PRINT 

GISPUT Amount of Regular Payments... ,YOUPAY 
Lae Enter the Prineiples«.",PRINGIPLE 
Lae, Enter the Annual Interest Rate...", 
INTEREST 

WES aro R Mie Enter the Number of Payments 

Year lyews™",NUMPAY 
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UYEARS=-CLOGC1-PRINCIPLE*CINTEREST/109@)/ 
CNUMPAY*YOUPAY))/CLOGC1+INTEREST/188/NUMPAY )* 
NUMPAY)) 

LIMONTH=INTCYEARS#12+.5) 

LYEARS=INTCMONTH/12) 


UMONTH=MONTH-YEARS#12 

PRINT ™ The Term of Your Loan is ™; YEARS; " 
years. and *s MONIES: * montis.” 

UINPUT "Calculate another or Quit (C/Q)?...", 
RESPONSE 


UUNTIL RESPONSE<>"C"™ AND RESPONSE <>!"c'! 
UDEND “Coodbye... I hope I helped you.” 
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ENDE XIT Leave loop if a condition is True 


Syntax: EXITIF condition THEN 
proclines 
ENDEXIT 


Function: ENDEXIT terminates an EXITIF test. You always 
use EXITIF/THEN/ENDEXIT inside a procedure loop. If the 
Boolean expression tested by EXITIF is true, BASICO9 exe- 
cutes the program statements between THEN and ENDEXIT 
and then transfers program operation outside the loop. If the 
condition tested by EXITIF is not true, loop execution contin- 
ues at the statement following ENDEXIT. 


Parameters: 
condition A comparison operation that returns either 
True or False, such as A=B, A<B, or 
A=B=C. 
proclines One or more statements to perform if the Boo- 


lean expression tested by EXITIF is True. 
For more information, see EXITIF/THEN/ENDEXIT 
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EN DIF Close IF statement 


Syntax: IF condition THEN 
action 
[ELSE 
secondary action] 
ENDIF 


Function: ENDIF terminates an IF/THEN condition test. If 
the condition tested by IF is true, BASICO9 executes the 
statements between THEN and ENDIF. If the condition tested 
by IF is not true, BASICO9 transfers execution to the proce- 
dure line following ENDIF or (optionally) executes the state- 
ments following ELSE. 


Parameters: 

condition A Boolean expression (produces a result of 
True or False). 

action A line number to which the procedure is to 
transfer execution. Action can also be a pro- 
gram statement. If action is a line number, do 
not include the ENDIF statement in the IF 
test. 

secondary A program statement. 

action 


For more information, see IF/THEN/ELSE/ENDIF. 
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ENDLOOP Close LOOP statement 


Syntax: LOOP 
statement(s) 
ENDLOOP 


Function: ENDLOOP terminates a procedure loop established 
by the LOOP command. BASICO9 endlessly executes all proce- 
dure statements between LOOP and ENDLOOP repeatedly 
unless a condition test within the loop (such as EXITIF’/ 
THEN/ENDEXIT, or IF/THEN) transfers execution outside of 
the loop. 


Parameters: 


statement(s) One or more procedure lines that execute 
within the loop. 


For more information, see LOOP/ENDLOOP. 
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ENDWHILE Close WHILE statement 


Syntax: WHILE condition DO 
proclines 
ENDWHILE 


Function: Forms the bottom of a WHILE loop. WHILE causes 
the procedure lines between DO and ENDWHILE to execute 
as long as the result of the expression following WHILE is 
true. Because the loop is tested at the top, the lines within 
the loop are never executed unless the expression is true. 


Parameters: 
condition A Boolean expression (produces results of True 
or False). 
proclines Are program lines to execute if the expression 
is true. 


For more information, see WHILE/DO/ENDWHILE. 
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EOF Test for end-of-file 


Syntax: EOF(path) 


Function: Tests for the end of a disk file. The function returns 
a value of True when it encounters an end-of-file; otherwise, it 
returns False. Use EOF with a READ or GET statement. 


Parameters: 
path The number of the path you are accessing. 
BASICO9 automatically stores a path number 
into the variable you specify during a 
CREATE or OPEN operation. 
Examples: 


IP EOP C#PATHS THEN 
CLOSE #PATH 
ENDIF 


Sample Program: 


This procedure redirects a listing of the current directory into a 
file named Dirfile. It then lists Dirfile to the screen. EOF tells 
the WHILE/ENDWHILE loop when the READ operation reaches 
the end of the file. 


PROCEDURE readfile 

UDIM A:STRING[88@] 

DIM PATH: BYTE 

NSHELE "DIR > dirtile™ 
JOPEN #PATH,"dirfile'™:READ 
UWHILE NOT EOFC#PATH) DO 
UJREAD #PATH,A 

UIPRINT A 

UENDWHILE 

CLOSE #PATH 

UEND 
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ERR Return error code 


Syntax: ERR 


Function: Returns the error code of the most recent error. 
BASICO9 automatically sets the ERR code to zero after you 
reference it. ERR is only useful when used in conjunction with 
BASICO9’s ON ERROR error trapping functions. 


See Appendix A for a list of all BASICO9 error codes. 
Parameters: None 


Examples: 


ERRNUM = ERR 

ITF ERRNUM = 218 THEN 

PRINT “File already exists. Please use another 
filename." 

ENDIF 


Sample Program: 


This procedure displays the contents of a file you select. If the 
file doesn’t exist (Error 216, Pathname not found), the procedure 
uses ERR to tell you. If an error other than Error 216 occurs, 
the procedure displays I can’t handle error xx, where xx is 
the code of the error. 
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PROCEDURE readfile 

CDIM READFILE:STRING; A:STRING(80]; PATH: BYTE 

1OLINPUT "Type the pathlist of the file to read...",READFILE 
HON ERROR GOTO 100 (* if an error occurs, skip to line 100. 
KIOPEN #PATH,READFILE:READ 

CWHILE EOFC#PATH)<>TRUE DO 

DREAD #PATH,A 

LIPRINT A 

LIENDWHILE 

KICLOSE #PATH 

LIEND 

{OOOERRNUMSERR (* store the error code in ERRNUM, 

DIF ERRNUM=216 THEN (* if file doesn’t exist say so. 

CIPRINT "I can’t find the file...Please try again." 

LION ERROR 

LIGOTO 18 

LIENDIF 


LICLOSE #PATH 


LIEND 
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ERROR Simulate an error 


Syntax: ERROR code 


Function: Simulates the error specified by code. You would 
mainly use this command to test ON ERROR GOTO routines. 
When BASICO09 encounters an ERROR statement, it proceeds 
as if the error corresponding to the specified code has 
occurred. Refer to Appendix A for a listing of error codes and 
their meanings. 


Parameters: 


code The code of the error you want to simulate. 
Examples: 


ERROR 207 

ERRNUM = ERR 

IF ERRNUM = 207 THEN 

PRINT “Memory is full. The current data is being 
saved to disk." 

ENDIF 


Sample Program: 


This program creates a file named Testl. Before creating the 
file, it checks to see if it already exists. If the file exists, the pro- 
cedure deletes it. An error trap catches any error that might 
occur. To test if the trap works for Error 216, “Pathname not 
found”, the statement ERROR 216 is inserted as the fourth line. 
After testing the trap to make sure it works, delete this line to 
use the procedure. 
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PROCEDURE errortest 


DIM PATH,ERRNUM: BYTE; RESPONSE:STRING[1] 
UBASE @ 

HON ERROR GOTO 19 (* set error trap 
DERROR 216 C* simulate error 
UIDELETE: “testi” 

GOTO 100 


19JERRNUM=ERR 

HIF ERRNUM=216 THEN 

OINPUT "File doesn’t exist...continue? 

CY/NO" ,RESPONSE 

HIF RESPONSE="N™ THEN 

HEND “Procedure terminated at your Pequest <i." 
WENDT F : 


LENDIF 

HON ERROR C* turn off error trap. 
199@UCREATE #PATH,"“testi":WRITE 

DEND 
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EXITIF/THEN/ENDEXIT 


Exit from loop if a condition is true 


Syntax: EXITIF condition THEN 
statement 
ENDEXIT 


Function: Use these statements with loop constructions (par- 
ticularly LOOP and ENDLOOP) to provide an exit for what is 
otherwise an endless loop. EXITIF performs a test of a Boo- 
lean expression, such as A<B. The THEN statement precedes 
any operation you want to execute if the expression is true. 
You must always follow EXITIF with an ENDEXIT. 


If the Boolean expression following an EXITIF is false, execu- 
tion of the program transfers to the statement immediately 
following the body of the loop (after the ENDEXIT statement). 
Otherwise, BASICO9 executes the statement(s) between 
EXITIF and ENDEXIT, then transfers control to the state- 
ment following the body of the loop. 


You can also use EXITIF and ENDEXIT with types of loop 
-constructions other than LOOP/ENDLOOP. 


Parameters: 
Boolean A comparison operation that returns either 
expression True or False, such as A=B, A<B, or 
A=B=C. 
statement An operation to be performed if the Boolean 


expression tested by EXITIF is True, such as: 
PRINT A is less than B. 
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Examples: 


Loe 

COUNT =COUNT +1 

EXITIF CUUNT>10@ THEN 
DUNE. ® “TRUE 

ENDEXIT 

PRINT COUNT 

X = COUNT/2 

ENDLOOP 


Sample Program: 


This procedure simulates a gambling machine by randomly 
selecting among several fruit names and displaying them. It 
gives you a starting stake of $25 and, depending on the combi- 
nation of fruit selected, it adds or subtracts from your stake. 


If your stake drops to zero, an EXITIF statement ends the proce- 
dure and tells you that you’re broke. 


PROCEDURE onearm 
DIM FRUIT1.FRUIT2, FRUITS, STAKE: INTEGERS FRUITCS): 
STRING[I6] 


USTAKE=25 
PRINT -\ PRINT “You have $3; STAKES ” to play 
WwEtha 


OFOR T=1 TO 8 

TREAD FRUITCT) 

NEXT T 

Loop 

OFRUIT1=RNDC7)+1. \FRUIT2=RNDC7)+1 \FRUIT3=RNDC7)+1 
OPRINT FRUITCFRUIT1); " "; FRUITCFRUIT2); " "; 
FRUITCFRUIT3) 

IF FRUITCFRUIT1)=FRUITCFRUIT2) AND FRUITCFRUIT1)= 
FRUITCFRUIT3) THEN STAKE=STAKE+10 

ELSE 

IF FRUITCFRUIT1)=FRUITCFRUIT2) OR FRUITCFRUIT1)= 
FRUITCFRUIT3) OR 

OF RUITCFRUIT2)=FRUITCFRUIT3) THEN 

TSTAKE=STAKE+1 

TELSE 

OSTAKE=STAKE-1 

JENDIF 

JENDIF 
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JREM exit play loop is stake is less than $1. 
NEXITIF STAKE<1 THEN 

OPRINT 

PRINT "You’re Busted...Better go home." 
DENDEXIT 

UPRINT “Your stake is now $"; STAKE; "," 
LIPRINT 

OPRINT 

UINPUT "Press ENTER to Ue Saal See es 
LENDLOOP 

DEND 

UDATA "ORANGE", "APPLE","CHERRY","LEMON'', "BANANA" 
UDATA "PEAR", "PLUM","PEACH" 
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EXP Return natural exponent 


Syntax: EXP(number) 


Function: Returns the natural exponent of number, that is, e 
(2.71828183) to the power of number. Number must be 
positive. 


This function is the inverse of the LOG function. Therefore, 
number = EXP(LOG(number)). 
Parameters: 


number A positive value. 


Examples: 


PRINT. EXPC2) 


Sample Program: 


This procedure calculates the exponent of values in the range 
0-1. 


PROCEDURE exprint 

FOR: T=2. To 1 STERP- .@3 

PRINT EXPCTI,EXPCT+, 8127 ,EXPCT+. 829 
ONEXT T 

LIEND 
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FALSE Assign Boolean value 


Syntax: variable=FALSE 


Function: FALSE is a Boolean function that always returns 
False. You can use FALSE and TRUE to assign values to Boo- 
lean variables. 


Parameters: None 


Examples: 


DIM TEST: BUOLEAN 
TEST#FALSE 


Sample Program: 


The procedure uses a Boolean variable to store True or False, 
depending on whether you answer some questions correctly or 
incorrectly. 


PROCEDURE quiz 

UDIM REPLY,VALUE:BOOLEAN; ANSWER:STRING[1]; 
QUESTION: STRING[8@] 

UFOR T=1 TO S 

UREAD QUESTION,VALUE 

UPRINT QUESTION 

UPRINT "CT) = TRUEQOOUDOUCF) = FALSE" 

BeRINT “Select. Tt or Fats 

LIGET #1,ANSWER 

UIF ANSWER="T" THEN 

HREPLY=TRUE 

TE oe 

UREPLY=FALSE 

HEND IF 

DIF REPLY=VALUE THEN 

UPRINT \ PRINT "That’s Correct...Good Show!" 
JELSE 

UPRINT “Sorry, you" re wrong...Better Luck next 
Lime.” 

ENDIF 

PRINT SPRINT ~\- PRINT 
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ONEXT T 
UDATA "In computer talk, CPU stands for Central 
Packaging Unit.", FALSE 


ODATA "The actual value of 64K is 65536 
bytes. , TRUE 

ODATA "The bits in a byte are normally numbered @ 
through 77%, TRUE 


ODATA "BASICO9 has four data types.",FALSE 
ODATA "The LAND function is a Boolean type 
operator.” ,FALSE 


HEND 
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F IX Round a real number 


Syntax: FIX(value) 


Function: Rounds a real number to the nearest whole number 
and converts it to an integer-type number. Fix performs a 
function that is the opposite of the FLOAT function. 


Parameters: 


value Any real number. 


Examples: 


A=RNDC1 0) 
PRINT FIXCA) 


Sample Program: 
This procedure displays the FIXed values of seven constants. 


PROCEDURE printfix 
OPRINT FIXG1 «23 
UPRINT: FF IXCT...39 
LIPRIANT -FEXCT 52 
HIPRINT FIX<€1.89 
UPRINT FIX€99.S566666) 
PRINT -FIRCS@.1) 
UPRINT FIXC.7654321) 
UIPRINT FIX€-12.44) 
UPRINT FIX€=9,99) 
NEND 
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FLOAT Convert from integer or byte to real 


Syntax: FLOAT(value) 


Function: Converts an integer- or byte-type value to real type. 
FLOAT performs a function that is the opposite of the FIX 
function. 


Parameters: 


value An integer- or byte-type number. 


Examples: 


DIM TEST: INTEGER 
TEST=44 
PRINT FLOATCTEST)/3 


Sample Program: 


This procedure uses FLOAT to produce a real number result of 
an inch to centimeter conversion. 


PROCEDURE convert 

ODIM T: INTEGER; MEASURE:STRING[11] 
OFOR T=1 TO 18 

OIF T=1 THEN 

COMEASURE="centimeter " 

HELSE 

OMEASURE="centimeters" 

DENDIF 

EPRINT Te“ s MEASURE: “ae “¢ FLOATCT)*.39873 


inches.” 
UNEXT T 
DEND 
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F OR/ NEXT/ STEP Establish a loop 


Syntax: 

FOR variable = init val TO end val [STEP value] 
[procedure statements] 

NEXT variable 


Function: Establishes a procedure loop that lets BASICO9 exe- 
cute one or more procedure statements a specified number of 
times. The variables you use can be either integer or real type 
and can be negative, positive, or both. Loops using integer 
values execute faster than loops using real values. 


BASICO9 executes the lines following the FOR statement until 
it encounters a NEXT statement. Then it either increases or 


decreases the initial value by one (the default) or by the value 
given STEP. 


Parameters: 
variable Any legal numeric variable name. 
init val Any numeric constant or variable. 
end val Any numeric constant or variable. 
value Any numeric constant or variable. 
procedure Procedure lines you want to be executed 
statements within the loop. 
Notes: 


e If you provide an initial value that is greater than the final 
value, BASICO9 skips the program loop entirely unless you 
specify a negative STEP value. Specifying a negative value 
for STEP causes the loop to decrement from the initial 
value to the end value. 
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@ When execution reaches the NEXT statement in a positive 
stepping loop, and the step value is less than or equal to 
the end value, BASICO9 branches back to the line after 
FOR and repeats the process. When the step value is 
greater than the end value, BASICO9 transfers execution to 
the statement following the NEXT statement. 


@ When execution reaches the NEXT statement in a negative 
stepping loop, and the step value is greater than or equal 
to the end value, BASICO9 branches back to the line after 
FOR and repeats the process. When the step value is less 
than the end value, execution continues following the NEXT 
statement. 


Examples: 


FOR COUNTER = 1 to 1808 STEP .5 
PRINT COUNTER 
NEXT COUNTER 


FOR X% = 18 TO 4 STEP --% 
PRINT X 
NEXT X 


FOR TEST = A TO B STEP ‘RATE 
PRINT TEST 
NEX?) TES! 


Sample Program: 


This procedure uses two nested FOR/NEXT loops to produce a 
multiplication table. 


PROCEDURE multable 
OPRINT USING "S45*","MULTIPLICATION TABLE" 
OPRINT 

ODIM I,J:INTEGER 

OFOR I=1 TO 9 

OFOR J=1 TO 9 

OIF J>1 THEN 

OPRINT I#J; TABCS*J); 
NELSE PRINT I*J; "| "3 
CENDIF 

ONEXT J 

OIF I=1 THEN 

OPRINT "" 


—— aaa acca 


11-56 


BASICO9 Command Reference / 11 


11-57 


BASICO09 Reference 


GET Read a direct-access file record 


Syntax: GET #path,varname 


Function: Reads a fixed-size binary data record from a file or 
device. Use GET to retrieve data from random access files. 


Although you usually use GET with files, you can also use it 
to receive data for any outputting device, such as a keyboard 
or another computer. By dimensioning a string variable to the 
length of input you want, you can use GET to read a specified 
number of keystrokes, then continue program execution with- 


out requiring [ENTER] to be pressed. 


For information about storing data in random access files, see 
Chapter 8, “Disk Files.” Also see PUT, SEEK, and SIZE. 


Parameters: 
path A variable name you choose in which BASICO9 
stores the number of the path it opens to the 
device you specify or one of the standard I/O 
paths (0, 1, or 2). 
varname The variable in which you want to store the 
data read by the GET statement. 
Examples: 


GET #PATH,DATAS 
GET #1,RESPONSES 


GET #INPUT,INDEXCX) 


Sample Program: 


This procedure directs a directory listing to a file named Dirfile. 
GET then reads the file, one character at a time in order to 
determine which characters are valid filename characters. The 
procedure creates a file containing all the filenames in the 
directory. 
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PROCEDURE filenames 

LIDIM DIRECTORY ,FILENAME:STRING; CHARACTER:STRING(1]; FILES(125):STRING(15]; 
PATH, COUNT, T: INTEGER 

LICOUNT=8 

LIFILENAME="" 

OFOR T=1 TO 125 (# initialize array elements to null, 

LIFILES(T)="" 

LINEXT T 

LIINPUT "Pathlist of directory to read...",DIRECTORY (# dir to copy. 
LION ERROR GOTO 18 

LIDELETE "dirfile" (* if dirfile already exists, delete it, 

1@LJON ERROR 

LISHELL "DIR "+DIRECTORY+" > dirfile" (* copy directory into file. 
LIOPEN #PATH,"dirfile":READ (+ open the file for reading. 

LIREPEAT 

LIREM Get characters from the file until the first carriage return - the 
beginning of the first filename. 

LIGET #PATH, CHARACTER (+ get characters from the file. 

LIUNTIL CHARACTER=CHR$(13) 

LIREM 

2@LLO0P 

LIEXITIF EQFC#PATH) THEN 

HGOTO 208 (* quit when end of file. 

LIENDEXIT 

LIREM get a character from the file until it finds a non-valid filename 
character, 

LIGET #PATH, CHARACTER 

LIREM 

LIEXITIF CHARACTER<="_" OR CHARACTER>"'z" THEN 

HGOTO 100 

LIENDEXIT 

LIFILENAME=FILENAME+CHARACTER (* build the filename. 

CIENDLOOP 

1OOLWHILE NOTCEQFC#PATH)) DO 

LIGET #PATH, CHARACTER (*-check for non-valid filename characters. 
LIEXITIF CHARACTER)" " AND CHARACTER<="z" THEN (* check if valid char. 
LICOUNT=COUNT+1 

LIFILESCCOUNT)=FILENAME (* store filename in array, 

LIPRINT FILENAME, (# display the extracted filename. 

LIFILENAME="" (# set variable to NULL. 

LIFILENAME=FILENAME+CHARACTER (* last character begins new filename. 
LIGOTO 20 (* go get the rest of filename. 

LIENDEXIT 

LIENDWHILE 

COOLICLOSE #PATH 
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ODELETE “dirfile" (* names are all in array so delete file. 
OCREATE #PATH,"dirfile":WRITE (# create the file again. 
DFOR T=1 TO COUNT 

CWRITE #PATH,FILES(T) (# fill the file with individual filenames. 
CNEXT T 

OICLOSE #PATH 

LIPRINT 

OPRINT "CUOOUO0 +The directory has "; COUNT; " entries” 
OPRINTO"OOOOO00oThey are now stored ina file named Dirfile." 
KIEND 
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GOSUB/RETURN 


Jump to subroutine/ Return from subroutine 


Syntax: GOSUB linenumber 


Function: Branches program execution to the specified line 


number. 


BASICO9 lets you write programs with line numbers or with- 
out. You can also mix numbered and un-numbered lines 
within a single procedure. This means that, to use GOSUB, 
you need to number only the first line of the subroutine to 
which you want to branch. 


Every subroutine you access with GOSUB must contain a 
RETURN statement. You can call a subroutine in this man- 
ner aS many times as you want. When BASICO9 encounters 
the RETURN, it transfers program execution to the line fol- 
lowing the GOSUB statement. 


You can precede GOSUB with a test statement, such as IF or 
WHEN, that makes branching conditional. 


You can nest GOSUB statements to any depth, depending on 
your computer’s free memory. 


Parameters: 
linenumber The number of the line where procedure exe- 
cution is to continue. 
Examples: 
GOSUB 1090 
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Sample Program: 


The following procedure asks you for two numbers and an opera- 
tor. It determines the line to jump to by the position of the oper- 
ator in a table. GOSUB sends the procedure to execute the 
proper routine. RETURN sends the execution back to the main 
routine. To quit, enter a negative value. 


PROCEDURE calc 

ODIM NUM1,NUM2:REAL; OP:STRING[11]; A: INTEGER 
1OINPUT "NUMBER 1 ‘*3;NUM1 
OIF NUM1<@ THEN 

UEND 

DENDIF 

DOINPUT "NUMBER 2 "sNUM2 
OINPUT “OPERATOR ™;O0P 
OA=SUBSTRCOP ,“"*+-#/*"") 

HOON A GOSUB 10,280,30,48,590 
UGOTO 1 


1@0PRINT NUM1+NUM2 \ RETURN 
2B0PRINT NUM1-NUM2 \ RETURN 
300PRINT NUM1*NUM2 \ RETURN 
4Q0PRINT NUM1/NUM2 \ RETURN 
SOOPRINT NUM1 NUM2 \ RETURN 


LEND 
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IF/THEN/ELSE/ENDIF 


Test a Boolean expression 


Syntax: IF condition THEN linenumber 
[ELSE 
secondary action 
ENDIF] 


IF condition THEN 
action 

[ELSE 

secondary action] 
ENDIF 


Function: Tests a Boolean expression and executes action if the 
expression is true. Optionally, the statements execute a sec- 
ondary action if the expression is not true. Each IF statement 
must be accompanied by THEN. If action is a line number, 
you can omit the ENDIF statement. For instance, both of the 
following statements operate in the same manner: 


IF T=S THEN 19 


IF T=S THEN 

GOTO 10 

ENDIF 

Parameters: 

condition A Boolean expression (produces True or False). 

linenumber A line to which the procedure is to transfer 
execution if condition is true. 

action One or more procedure statements to be exe- 
cuted if condition is true. 

secondary One or more procedure statements to execute 

action if condition is false. 
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Examples: 
IF A>B THEN 108 


IF A<B THEN 198 
EL or 

A=A-1 

ENDIF 


IF TEST=TRUE THEN 
PRINT "The test is a SUCCcCesS..."™ 
ENDIF 


IF A «< B THEN 

PRINT "A is less than B" 
Poe 

PRINT "B is less than A" 
ENDIF 


Sample Program: 


The following procedure is a purge procedure. Use it only with 
the GET Sample Program to delete one or more files from your 
current directory. 


The Filenames procedure (see GET) stores the current directo- 
ry’s filenames in Dirfile. This procedure reads Dirfile, displays 
all the filenames, then asks you for a wildcard. Type in charac- 
ters that identify a group of files you want to delete. The pro- 
gram deletes all files that contain, in the same order and case, 
the characters you type. 


For instance, if you have four files named Test, Filel, File2, and 
File3, and you type a wildcard of “File,” the procedure deletes 
Filel, File2, and File3, but does not delete Test. Delete all of the 
files in a directory by typing “*” as the wildcard. 


Use this program carefully. Be sure you are in the right 
directory and that the wildcard characters you type are not con- 
tained in filenames other than the ones you want to delete. You 
might want to add a prompt to the procedure that lets you con- 
firm each deletion before it happens. 


11-64 


BASICO9 Command Reference / 11 


PROCEDURE purge 

UDIM PATH: INTEGER 

UDIM NAMEC188):STRING 

UDIM WILDCARD:STRING 

X= 

JOPEN #PATH,"dirfile'™:READ 

UWHILE NOTCEOFC#PATH)) DO 

UX=X+1 

READ #PATH,NAMECX) 

NENDWHILE 

FOR T= TO xX 

UPRINT NAMECT), 

UINEXT T 

UINPUT "Wildcard Characters...™",WILDCARD 
UPGR T<? Ta -x 

WON ERROR GOTO 182 

UIF SUBSTRCWILDCARD,NAMECT))>@ OR WILDCARD=""*" 
THEN 

PRINT "DELETING “Ss (NAMECTI: “- coxvvar “ 
UDELETE NAMECT) 

LIENDIF 

1OUNEXT T 

WIEND 

1O@UPRINT "* * * ERROR * * * "; NAMECT): "™ cannot 
be deleted. ,continuing.,™ 

UGOTO 190 
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INKEY Read a keypress 


Syntax: RUN INKEY (string) 


Function: Reads a keypress, and stores the character of the 
key in the specified string variable. 


Parameters: 
string is a string variable into which INKEY stores 
the character you press. 
Examples: 
DIM CHAR:STRING[11] 
C a A a =— '008 
WHILE CHAR=""" DO 
RUN INKEYCCHAR) 
ENDWHILE 


PRINT ASCCCHAR) 
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Sample Program: 


PROCEDURE Calculate 

UDIM CHAR:STRING[1] 

UDIM LOOKUP:STRING[7] 

UDIM FIRST,SECOND: REAL 

UDIM FLAG: INTEGER 

DLOOKUP="+-*#/%<¢>" 

1 FLAG=@ \CHAR=""" 

UPRINT “Enter the first number to evaluate..."; 
UINPUT FIRST 

UIF FIRST=@ THEN 


UGOTO 100 
DENDIF 
UPRINT “Enter the second number to evaluate...":; 


UINPUT SECOND 

JPRINT “Press the key of the operator you want to 
UEesv.” 

EP RE Shae soe ae he A ARE a 
UWHILE CHAR="" DQ 

RUN INKEYCCHAR) 

NENDWHILE 

UIPRINT 

UFLAG=SUBSTRCCHAR, LOOKUP) 

UON FLAG GOTO 18,20,30,40,50,60,70 
Ue PRINT: FIRST#SECOND: \ GOTO: “4 


ev PRINT FIRST=SECOND \ GOTO: 1 
3@ PRINT FIRST*SECOND \ GOTO 1 
40 PRINT PIRST/SECOND \ GOTO 4 
58 PRINT FIRST*SECOND \ GOTO 1 
68 PRINT FIRST<SECOND \ GOTO 1 


78 PRINT FIRST>SECOND \ GOTO 1 

188 PRINT "Procedure Terminated Due to @ 
IHPUlss 4 

HEND 
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INPUT Get data from a device path 


Syntax: INPUT [#path,] [prompt,] variable [, variable...] 


Function: INPUT accepts input from the specified path. (The 
default is the keyboard.) When a procedure encounters 
INPUT, it displays a question mark and awaits data from the 
specified path. If you provide a string type prompt for INPUT, 
it displays the text of the prompt, rather than a question 
mark. 


INPUT stores the data it collects in the variable you specify. 
The type of the receiving variable must match the type of 
data received. 


Because INPUT sends data (the question mark prompt or the 
user-specified string prompt), it is really both an input and an 
output statement. This means that, if you use a path other 
than the standard input path, you should not use the 
UPDATE mode. If you do, the prompts produced by INPUT 
write to the file specified by the path number. 


If the data received does not match the type of data INPUT 
expects, it displays the message: 


**INPUT ERROR - RETYPE** 


followed by a new prompt. You must then enter the entire 
input line, of the correct type, to satisfy INPUT. For more 
information, see GET. 
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Parameters: 
path Either a variable containing the path number, 
_, or the absolute path number to the file or 
device from which you want to receive input. If 
you want to receive input from the keyboard, 
do not include a path number. 
prompt Text you type as a message to be displayed 
when BASICO9 executes an INPUT statement. 
variable The variable name in which you want to store 
the data received by INPUT. The type of vari- 
able must match the type of input. 
Examples: 


INPUT NUMBER,NAME$ ,LOCATION 
INPUT #PATHY Xs ¥,2 
INPUT “What is your selection: “;CHOICE 
c™ INPUT #HOST,"What’s your ID number? ",IDNUM 


Sample Program: 


This procedure calculates the day of the week for a specified 
date. It asks you for the date using the INPUT command. 


PROCEDURE weekday 

UDIM X,Y,D,M,CALC: INTEGER; DAY,MONTH:STRING([2]; 
YEAR: STRING[I 4]; WEEKDAY €7):STRING[Q] 

JDIM ANUM,BNUM,CNUM,DNUM,ENUM,FNUM,GNUM,HNUM, 
INUM: INTEGER 

PRINT USING "S88 ","Day of the Week Program "rar 
any year atier 1752" 


PRINT 

WPRINT “Enter day Ce.g.. 889% "s A: TNPUT DAY 

PRINT *- Enter month Ces,9g. 123 %. INPUT MONTH 

UPRINT = -Enter year Ceag. 198626 ": \ INPUT -YEAR 
o™ JY=VALCYEAR) \M=VALCMONTH) \D=VALCDAY) 


FOR x=1 TO 7 
JREAD WEEKDAYCX) 
UINEXT xX 
UANUM=INTC.6+1/M) 
JBNUM=Y-ANUM 
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UCNUM=M+12*ANUM 
UDNUM=BNUM/ 108 
DENUM=INTCDNUM/ 4) 
UFNUM=INTCDNUM) 
UGNUM=INTCS*BNUM/ 4) 
DHNUM=INTC13*CCNUM+19/5) 
UDINUM=HNUM+GNUM-FNUM+ENUM+D-1 
OINUM=INUM-7* INTCINUM/ 7) +1 


PRINT 
UPRINT “The day of the week on "5 M; "7"; D; 
7s Vs pe, os WEEKDAY CINUM2 


ODATA “Sunday™,™"Monday™, "Tuesday", “Wednesday”, 
“The sday' "Friday, “saturday” 
UEND 
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IN T Convert real number to whole number 


Syntax: INT(value) 


Function: Converts a real number to a whole number by trun- 
cating any fractional part of the real number. 
Parameters: 


value Any negative or positive real number. 


Examples: 
PRINT INTC77.89) 
PRINT INTCNUM) 
PRINT INTC-8.12) 


Sample Program: 


The RND function produces real numbers. This procedure uses 
INT to convert the real RND output to integer values. 


PROCEDURE integer 
UDIM T: INTEGER 
UFOR T=1 TO 1@ 
UR=RNDCS8@)-25 
UPRINT R,INTCR) 
EINEXT 7 

WEND 
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KILL Remove a procedure from memory 


Syntax: KILL procedure 


Function: Unlinks (removes) an external procedure from the 
BASICO9 procedure directory. If the procedure is not external, 
but resides in BASIC09’s workspace, KILL has no effect. 


Use KILL to remove auto-loaded (packed) procedures that are 
called by RUN or CHAIN. You can also use KILL with auto- 
loading procedures as a method to overlay programs within 
BASICO9. 


Warning: Be certain you do not KILL an active proce- 
dure. Also be certain that when you use RUN and KILL 
together, that both statements use the same string vari- 
able that contains the name of the procedure to RUN 


and KILL. 
Parameters: 
procedure The name of the external procedure you want 
to KILL. Procedure can either be a name or a 
variable containing the procedure name. 
Examples: 
PROCEDURENAME$ = "AVERAGE" 


RUN PROCEDURENAME $ 
KILL PROCEDURENAMES$ 


INPUT "Which test do you want to run? ",TESTS$ 
RUN TESTS$ 
Kit Pests 
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Sample Program: 


This procedure calls a procedure named Show to display ASCII 
values on the screen. When it no longer needs the Show proce- 
dure, it removes Show from memory using KILL. 


PROCEDURE produce 

LIDIM T, UsINTEGER 

CIDIM NUM,NUM1 ,NUM2, TABLE ,PROCNAME: STRING 
CIPROCNAME=SHOW 

LKITABLE="'123456789ABCDEF" 
LIFOR T=8 TO 15 

LIFOR U=1 TO 15 

LINUM1 =MID$CTABLE,T,1) 

LINUM2=MID$CTABLE,U,1) 

LINUM=NUM1+NUM2 (* parameter to pass to Show. 


LIRUN PROCNAMECNUM) 

LINEXT U 

LINEXT T 

UIKILL "PROCNAME' (*# remove Show from the workspace. 


UEND 


PROCEDURE SHOW 

LIPARAM NUM:STRING 
USHELL "DISPLAY "+NUM 
LEND 
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LAND Returns the logical AND of two numbers 


Syntax: LAND(num1,num2) 


Function: Performs the logical AND function on a byte- or 
integer-type value. The operation involves a bit-by-bit logical 


AND of the two numbers you specify. For instance, if you 
LAND 5 and 6, the logic is like this: 


Decimal 5 = Binary 0101 
Decimal 6 = Binary 0110 


0101 
AND 0110 


= 0100 = 4 Decimal 


Parameters: 
num! A byte- or integer-type number. 
num2 A byte- or integer-type number. 
Examples: 


PRINT LANDC11,12) 


PRINT LANDC $20 ,$FF) 


Sample Program: 


The following procedure asks eight questions and uses the eight 
bits of one byte (contained in the variable STORAGE) to indicate 
either a “yes” or “no” answer. If the answer is “yes,” it sets a 
corresponding bit to 1. If the answer is “no,” it sets a corre- 
sponding bit to 0, using LAND. This procedure operates in con- 
junction with the sample program for LXOR. 
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PROCEDURE questions 


LIFOR T 
LIREAD 


OGET # 
LIPRINT 
LIF AN 


LIELSE 


LENDIF 
LX=X+2 
LINEXT 


LIEND 

LIDATA 
LIDATA 
LIDATA 
LIDATA 
LIDATA 
LIDATA 
LIDATA 
LIDATA 


ale 
QUESTION 


0, ANSWER 


SHER="y" 


r 


"Do you 
"Do you 
"Do you 
"Do you 
"Do you 
"Do you 
"Do you 
"Do you 


LIPRINT QUESTION; " (Y/N)? "; 


OR ANSWER="Y" THEN 


RUN summary (STORAGE) 


have more than 


use your 
use your 
use your 
use your 
use your 
Use your 


Color 
Color 
Color 
Color 
Color 
Color 


one Color Computer" 

for games" 

for word processing" 

for business applications" 


Computer 
Computer 
Computer 
Computer 
Computer 
Computer 


CIDIM QUESTION:STRING(G01; T: INTEGER; X,STORAGE:BYTE 
LIDIM ANSWER: STRING(1] 


LISTORAGE=LOR(STORAGE ,X) (* OR STORAGE if yes, 


LISTORAGE=LAND(STORAGE ,LNOT(X)) (# LAND STORAGE with NOT value if no. 


at home" 


at the office" 
more than two hours a day" 
share your Color Computer with others" 
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LE FT Returns characters from the left portion 
of a string 


Syntax: LEFT$(string,length) 


Function: Returns the specified number of characters from the 
specified string, beginning at the leftmost character. If length 
is the same as or greater than the number of characters in 
string, then LEFT$ returns all the characters in the string. 


Parameters: 
string A sequence of ASCII characters or a string 
variable name. 
length The number of characters you want to access. 
Examples: 


PRINT LEFTSC"HUTDOG™,32 


PRINT LEFT$CA$,6) 


Sample Program: 


The following procedure extracts the first name from a list of ten 
names with the LEFT$ function. 


PROCEDURE firstname 

DDIM NAMES:STRING; FIRSTNAME:STRING(1@] 
CPRINT "Here are the first names:" 

CIFOR T=1 TO 18 

LIREAD NAMES 

CPOINTER=SUBSTR(" ",NAMES) (* find space between first and last names. 
CIFIRSTNAME=LEFTS$CNAMES ,POINTER-1) (* extract first name. 
CIPRINT FIRSTNAME (* print first name. 

LINEXT T 

LIEND 

ODATA "Joe Blonski","Mike Marvel","Hal Skeemish","Fred Laungly" 


DIDATA "Jane Mistey", "Wendy Paston","Martha Upshong", "Jacqueline Rivers" 
CIDATA "Susy Reetmore", "Wilson Creding" 
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LEN Returns the length of a string 


Syntax: LEN(string) 


Function: Returns the number of characters in a string. 
Counts blanks or spaces as characters. 


Parameters: 
string A literal string or a variable containing string 
characters. 
Examples: 


PRINT LENC™ABCDEFGHIUJKLIN") 
PRINT LENCNAME$) 


NAME$ = "JOE" 
ADDRESS$ = "2244 LANCASTER" 
TOTALLEN = LENCNAME$)+LENCADDRESS$ ) 


Sample Program: 


The following procedure uses LEN to determine which name in a 
list is longest. 


PROCEDURE longname 

LIDIM NAMES ,LNAME:STRING; LONGEST,LENGTH: INTEGER 

LINAMES="" \LNAME="" \LENGTH=@ \LONGEST=0 

CIFOR T=1 TO 10 

LIREAD NAMES 

LILENGTH=LENCNAMES ) 

LIF LONGEST<LENGTH THEN 

ILONGEST=LENGTH 

CILNAME=NAMES 

LIENDIF 

LINEXT T 

LIPRINT "The longest name is "; LNAME; " with "; LONGEST; " characters." 
LIEND 

LIDATA "Joe Blonski","Mike Marvel","Hal Skeemish","Fred Laungly" | 
UIDATA "Jane Misty", "Wendy Paston", "Martha Upshong", "Jacqueline Rivers" 

VIDATA "Susy Reetmore", "Wilson Creding" 


IS LD SIE EES ELSE OY ET a I ET IT ES SEP I SE I I TS 
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LET Assigns a variable’s value 


Syntax: [LET] variable = expression 


Function: Assigns a value to a variable. BASICO9 does not 
require the LET statement to assign values but does accept it 
in order to be compatible with versions of BASIC that do 
require it. 


Parameters: 
variable The variable to which you want to assign a 
value. 
expression Either a numeric or string constant or a 
numeric or string expression. 
Notes: 


e The result of the LET expression must be of the same type 
as, or compatible with, the variable in which it is stored. 


e BASIC09’s assignment function accepts either = or := as 
assignment operators. The := form helps to distinguish 
assignment operations from comparisons (test for equality) 
and is compatible with Pascal programming. 


@ Use BASIC09’s assignment function to copy entire arrays or 
complex data structures to another array or complex data 
structure. The data structures do not need to be of the 
same type or shape, but the size of the destination struc- 
ture must be the same as or larger than the source struc- 
ture. This means the assignment function can perform 
unusual type conversions. For example, you can copy a 
string variable of 80 characters into a one-dimensional 
array of 80 bytes. 
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Examples: 
LET A = 5 
LET A := B 
ANSWER = A * B 
LET NAME$ := "JOE" 
NAME $ = FIRSTNAME$ + " " + LASTNAMES 


Sample Program: 


This procedure uses LET to assign a random value to the vari- 
able R. 


PROCEDURE getint 
UDIM T: INTEGER 
FOR T=1 TO 10 
ULET R=RNDC50)-25 
UPRINT R,INTCR) 
LINEXT T 

END 
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LNOT Performs a logical NOT on a number 


Syntax: LNOT(value) 


Function: Performs the logical NOT function on an integer or 
byte type number. The operation involves a bit-by-bit logical 
complement operation of the number you specify. For instance, 
if value is 188, the logic looks like this: 


188 Decimal = 10111100 Binary 


NOT 10111100 
= 01000011 


01000011 Binary = 67 Decimal 


LNOT changes each bit in a binary number to its complemen- 
tary binary value—all 1 values become 0 and all 0 values 
become 1. LNOT returns an integer result; it is not a Boolean 
operator. 


Parameters: 
value Any decimal or hexadecimal integer or byte 
number. Precede hexadecimal numbers with $. 
Examples: 


PRINT LNOTC88) 
A = LNOTCB) 


A = LNOTC$44) 


Sample Program: 


This procedure uses one byte (contained in the variable STOR- 
AGE) to indicate the results of eight questions. Each bit in the 
byte indicates a Yes or No answer (Yes=1 and No=0). The com- 
bination logic of LAND and LNOT masks the byte X so that it 
affects only the appropriate bit of STORAGE to set it to 0 if the 
answer is No. LOR sets the appropriate bit to 1 if the answer is 
Yes. The procedure operates in conjunction with the LXOR sam- 
ple program. 
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PROCEDURE questions 

LIDIM QUESTION:STRING(60)]; T: INTEGER: X,STORAGE:BYTE 
CIDIM ANSWER: STRING(1] 

LIX=1 

LIFOR T=1 10 8 

CIREAD QUESTION 

LIPRINT QUESTION; " (Y/N)? ": 

CIGET #0, ANSWER 

RINT 

LIF ANSWER="y" OR ANSWER="Y" THEN 
LISTORAGE=LOR(STORAGE,X) (* Answer is yes; Set bit to 1; 
LIELSE 

LISTORAGE=LAND(STORAGE ,LNOT(X)) (* Answer is no, set bit to @. 
LIENDIF 

LX=X#2 

LINEXT T 

LIPRINT STORAGE 

RUN summary(STORAGE) 

CIEND 

LIDATA "Do you have more than one Color Computer" 

LIDATA "Do you use your Color Computer for games" 

LIDATA "Do you use your Color Computer for word processing" 


LIDATA 
LIDATA 
UDATA 


LIDATA 


CIDATA "Do you 


"Do you 
"Do you 
"Do you 
"Do you 


use your Color Computer for business applications" 
use your Color Computer at home" 

use your Color Computer at the office" 

use your Color Computer more than two hours a day" 
share your Color Computer with others" 
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LOG Returns natural logarithm 


Syntax: LOG(number) 


Function: Computes the natural logarithm of a number that 
is greater than zero. BASICO9 returns the logarithm as a real 
type result. 


Parameters: 


number Any integer, byte, or real number. 


Examples: 
PRINT LOGC3.14159) 
LOGVALUE = LOGC88/P1) 


Sample Program: 


This procedure calculates the natural log and the log to base 10 
of the values 1-7. 


PROCEDURE logs 
DIM NUM,T: INTEGER 
LIFOR T=1 TO 7 
OPRINT "The LOG of "s T; " to the natural base = 
ec UGC TD 

DPRINT “The LOG of “ss Ts -*" to base 10 °=-"s 
LOG1@CT) 

LIPRINT 

UINEXT T 

LIEND 
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LOG10 Returns base 10 logarithm 


Syntax: LOG10(number) 


Function: Calculates the base 10 logarithm of a number. 
BASIC09 returns the logarithm as a real number. 


Parameters: 


number Any byte, integer, or real value. 


Examples: 
PRINT LOG10C€$45) 
PRINT LOG10CA) 
PRINT LOG10C€A/12) 


Sample Program: 


This procedure calculates the natural log and the log to base 10 
of the values 1-7. 


PROCEDURE logs 

UDIM NUM,T: INTEGER 

UFOR T=t TO 7 

UPRINT "The LOG of "; Ts; " to the natural base = 
me LUGE T 2 

UPRINT “The LOG of "s T: " to base 19 = a 
LOG1I@CT) 

UPRINT 

UNEXT T 

UEND 
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LOOP/ENDLOOP 


Establishes/Closes a loop 


Syntax: LOOP 
statement(s) 
ENDLOOP 


Function: Establishes a loop in which you can install EXITIF 
tests at any location. The LOOP and ENDLOOP statements 
define the body of the loop. EXITIF tests for a condition 
which, if TRUE, causes alternate actions, the transfer of pro- 
cedure execution to another routine, or both. 


If you do not include an EXITIF statement, the loop cannot 
terminate. 


Parameters: 
statement(s) One or more procedure lines to execute within 
the loop. 
Examples: 
LOOP 


COUNT = COUNT+1 

EXITIF COUNT 2 489° THEN 
DONE = TRUE 

ENDEXIT 

PRINT COUNT 

X=COUNT/2 

ENDLOOP 


INPUT Xa¥ 

LOOP 

PRINT 

EXITIF X<@ THEN 

PRINT "X became @ first" 
END 

ENDEXIT 

Kose 4 

EXITIF Y=@.- THEN 

PRINT "Y became @ first" 


a 
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END 
ENDEXIT 
¥uy=4 
ENDLOOP 


Sample Program: 


This procedure simulates a gambling machine that awards cash 
returns depending on a random selection of kinds of fruits. You 
begin with a stake of $25 and win or lose according to random 
selections of the procedure. 


The program uses LOOP/ENDLOOP to keep operating until you 
run out of cash. 


PROCEDURE bandit 

UDIM FRUIT1,FRUIT2,FRUIT3,STAKE: INTEGER; 
FRUITC18):STRING[6] 

USTAKE=25 

UIPRENT PRINT “You have $™* STAKEs ™ to play 
Wirth. 

FOR T=1 TO 1@ 

UREAD FRUITCT) 

UNEXT T 

LOOP 

UFRUIT1=RNDC9)+1 \FRUIT2=RNDC9)+1 \FRUIT3=RNDC9) +1 
UPRENT FRUITCRRUITIDs. 8 2 FRUITCERUIT2)3 * 
PRUITCFRUIT3) 

UIF FRUITCFRUIT1)=FRUITCFRUIT2) AND FRUITCFRUIT1)= 
FRUITCFRUIT3) THEN 

USTAKE=STAKE+12 

i ry = 

JIF FRUITCFRUIT1)=FRUITCFRUIT2) OR FRUITCFRUIT2)= 
FRUITCFRUIT3) THEN 

USTAKE=STAKE+2 

HELSE 

UIF FRUITCFRUIT1)=FRUITCFRUIT3) THEN 
USTAKE=STAKE +1 

ELSE STAKE=STAKE-1 

HENDIF 

LIENDIF 

HENDIF 

HEXITIF STAKE<1 THEN 

UPRINT 

PRINT "You’re Busted...Better go home." 
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PROCEDURE questions 

UDIM QUESTIONSSTRING(6@8)]= TI NTEGER: 
X,STORAGE* BYTE 

UDIM ANSWER: STRING[1] 

LIX = 1 

FOR T=T To 8 

UREAD QUESTION 

UPRINT QUESTION: * ©Y/NJ? 5 

GET #8,ANSWER 

LIPRINT 

ULF ANSWER ="*yv" OR ANSWER="Y¥" “THEN 
UISTORAGE=LORCSTORAGE, X) 

ELSE 

USTORAGE=LANDCSTORAGE ,LNOTCX)) 

VEND TF 

LIX=X*2 

LINEXT T 

LIPRINT STORAGE 

RUN summaryCSTORAGE) 

LIEND 

UDATA "Do you have more than one Color Computer" 
UDATA "Do you use your Color Computer for games" 
UDATA "Do you use your Color Computer for word 
processing” 

UDATA "Do you use your Color Computer for business 
applications” 

UDATA "Do you use your Color Computer at home" 
UDATA "Do you use your Color Computer at the 
office™ 

UDATA "Do you use your Color Computer more than 
two hours a day" 

UDATA "Do you share your Color Computer with 
others" 
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LXOR Returns logical XOR of two numbers 


Syntax: LXOR(valuel,value2) 


Function: Performs the logical XOR function on two-byte, or 
integer-type, values. For instance, if you LXOR the numbers 5 
and 6 the logic is like this: 


Decimal 5 = Binary 0101 


Decimal 6 = Binary 0110 
0101 

LXOR 0110 

= 0011 = 3 Decimal 


If one bit or the other bit in the evaluation is 1, but not both, 
LXOR returns a result of 1. Otherwise, LXOR returns a 
result of 0. 


Parameters: 
valuel A byte or integer number. 
value2 A byte or integer number. 
Examples: 


PRINT LXORC11,12) 


PRINT LXORC$2@,$FF) 


Sample Program: 


The following program summarizes the results of the sample 
program for LOR. The LOR program stored the answers to eight 
questions in a single byte. This procedure reads the byte and 
displays appropriate comments. LXOR checks to see if two of the 
answers are “yes” or “no.” 
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ENDEX ALT 

PRINT "Your stake is now $"3; STAKE; "." 

OPRINT 

PRINT 

OINPUT “Press ENTER to pull again...",2Z$ 
OENDLOOP 

HEND 

ODATA “ORANGE","APPLE","CHERRY","LEMON", "BANANA" 
ODATA “PEAR"™,"PLUM", “PEACH, "GRAPE","APRICOT™ 


ne ee 
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LOR Returns logical OR of two numbers 


Syntax: LOR(valuel,value2) 


Function: Performs the logical OR function on a byte- or 
integer-type value. The operation involves a bit-by-bit logical 
OR operation on two values. For instance, if you LOR the 
numbers 5 and 6, the logic is like this: 


Decimal 5 = Binary 0101 
Decimal 6 = Binary 0110 


0101 
OR 0110 


= 0111 = 7 Decimal 


If one bit or the other bit is 1, LOR returns a result of 1. 
Otherwise, LOR returns a result of 0. 


Parameters: 
valuel A byte or integer number. 
value2 A byte or integer number. 
Examples: 


PRINT LORETT. Te) 


PRINT LORC$20,$FF) 


Sample Program: 


This procedure stores the answers to eight “yes” or “no” ques- 
tions in one byte, named STORAGE. If you answer “yes” to a 
prompt, the procedure sets a corresponding bit to 1. If you 
answer “no” to a prompt, the procedure sets a corresponding bit 
to 0. The procedure uses LOR to set bits to 1 by masking all bits 
except the one it needs to set. The procedure operates in con- 
junction with the LXOR sample program. 
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PROCEDURE summary 

DIM TeINTEGER: A,B X. TEST, TESTS: BYTE? SUMMARY: 
STRING(S@ 3 

OPARAM STORAGE: BYTE 

LA=0 \B=@ 

PRINT \ PRINT 

OPRINT “The following iS a summary of the 
questionnaire answers:" 

UPRINT 

DPRINT “The surveyee: * 

LIX = 1 

OFOR T=1 TO 8 
OTEST=LANDCSTORAGE , X) 
DREAD SUMMARY 

OIF TEST>@ THEN 

OPRINT TABC19); SUMMARY 
ENDIF 

UX=X*2 

UNEXT T 

OIF LANDCSTORAGE ,128)>@ THEN 
LIA=1 

LIENDIF 

OIF LANDCSTORAGE ,64)>8 THEN 
LIB=1 

DIENDIF 
OTEST2=LXORCA,B) 


OIF TEST2@=1 THEN 
EPRINT “This: computer owner either uses the 
computer? 

OPRINT “more than two hours a day or shares it 
with others." 

OPRINT "This is a heavy use situation.” 

DENDIF 

OTEST2=LANDCA,B) 

[LE TEST2=1 THEN 

OPRINT “This computer user uses the computer more 
than two" 

OPRINT “hours per day and shares it with others. 
This is a" 

OPRINT “super heavy use situation.” 

HENDIF 

WIEND 

ODATA "Uses more than one computer" 

ODATA “Plays games" 


ee mene namrnrierneeneemmmesmmereeeemerneene meee memes asaaaaaaacaaaaamaaaaaaaaaaamaamaaamammaaamaaam 
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“Uses the computer for word processing™ 
“Uses the computer for business" 

“Keeps a Color Computer at home" 

"Keeps a Color Computer at the office" 
“Uses the computer more than two hours a 


“Shares the computer with others" 
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MID$ Returns characters from within a string 


Syntax: MID§(string,begin,length) 


Function: Returns a substring length characters long, begin- 
ning at begin. Use MID$ to “take apart” a string consisting 
of a number of elements. 


Parameters: 
string A sequence of string type characters or a 
string type variable. 
begin The position (an integer value) in string of the 
first character to retrieve. 
length The number of characters you want to retrieve. 
Examples: 
NAMES = “JONES, JOHN M.™ 


LASTNAME$S = MIDSCNAMES ,8,6) 
FIRSTNAME$ = MID$CNAMES,1,5) 
INITIAL$ = MID$CNAMES$ ,15,2) 


Sample Program: 


This procedure reverses a word or phrase you type. MID$ reads 
each character in your phrase from the end to the beginning. 


PROCEDURE reverse 

ODIM PHRASE:STRING; T,BEGIN: INTEGER 
PRINT “Type a word or phrase you want (ee. 
reverse:"'; 

WJPRINT 

OINPUT PHRASE 


UBEGIN=LENCPHRASE ) 
OPRINT “This is how your phrase looks backwards:" 
(FOR T=BEGIN TU 1 STEP =1 

DOPRINT MID$CPHRASE,T,1); 

UNEXT T 

PRINT 

HIEND 


—— aaa 
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MOD Returns modulus of a division 


Syntax: MOD(number1,number?2) 


Function: Returns the modulus (remainder) of a division. 
MOD divides numberl by number? and calculates the remain- 
der. You can use MOD to put a limit on a numeric variable. 
For instance, regardless of the value of X, MOD(X,3) produces 
numbers only in the range 0 through 2. MOD(X,5) produces 
numbers only in the range of 0 through 4. 


You can use MOD to cause repeating sequences. For instance, 
in a loop, MOD(X,3) produces a repeating sequence of 0, 1, 2, 
where X increases by 1 in each step of the loop. 


Parameters: 
number! A byte, integer or real number dividend. 
number2 A byte, integer or real number divisor. 
Examples: 


PRINT MODC99,5) 
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Sample Program: 


This procedure uses MOD to execute repeatedly routines that 
display asterisks on the screen. There are eight subroutines that 
the MOD function selects over and over through 100 passes. 


PROCEDURE stardown 

UDIM TeINTEGER 

OSHELL “TMODE -PAUSE™ 

OFOR T=1 TO 1900 

OON MODCT,8)+1 GOSUB 10,20,30,48,50,60,70,80 
UNEXT T 

OSHELL “"TMODE PAUSE" 

OEND 

1@0OPRINT USING "S16*","*#" \ RETURN 
2G0PRINT USING "S190°","#*" \ RETURN 
3O0PRINT USING "S10%","#*##" \ RETURN 
4@0PRINT USING "S10", "##*#"™" \ RETURN 
SOOPRINT USING "S1Q%", eeeee" \ RETURN 
GO@OPRINT USING "S19", eee" \ RETURN 
7O@OPRINT USING "S1@%","#**" \ RETURN 
S8@OPRINT USING "S10*","*#" \ RETURN 
HEND 
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N E XT Causes repetition in a FOR loop 


Syntax: FOR variable = init val TO end val [STEP 
value] 
[procedure statements] 
NEXT variable 


Function: NEXT forms the bottom end of a FOR/NEXT loop. 
Any program statements between FOR and NEXT are exe- 
cuted once for each repetition of the loop, from the initial 
value to end value. 


Parameters: 
variable Any legal numeric variable name. 
init val Any numeric constant or variable. 
end val Any numeric constant or variable. 
value Any numeric constant or variable. 
procedure Procedure lines you want to execute within 
statements the loop. 


For more information, see FOR/NEXT/STEP. 
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NOT Returns the complement of a value 


Syntax: NOT(value) 


Function: Returns the logical complement of a Boolean value 
or expression. 


Parameters: 
value A Boolean value (True or False), or an expres- 
sion resulting in a Boolean value. 
Examples: 


DIM TEST:BOOLEAN 
WHILE NUPCTESTS: De 
A=A+1 

TEST #A=B 

ENDWHILE 


Sample Program: 


This procedure redirects the current directory listing to a file 
named Dirfile. It then opens Dirfile and reads the contents, dis- 
playing each line on the screen. It uses NOT in a WHILE/END- 
WHILE loop to make sure that the end of the file has not been 
reached before trying to read another entry. 


PROCEDURE readfile 

UDIM A:STRING([88@] 

JDIM PATHS BY Fe 

MSHELL “DIR > dirfile” 
OPEN #PATH,"dirfile":READ 
OWHILE NOT EOQFC#PATH) DO 
UREAD #PATH,A 

UP-RINT A 

NENDWHILE 

DCLOSE #PATH 

HEND 
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ON ERROR/GOTO 


Establishes an error trap 


Syntax: ON ERROR [GOTO linenum] 


Function: Sets an error trap that transfers control to the spec- 
ified line number in a procedure. This lets your program 
recover from an error and continue execution. To use these 
commands, your program must have at least one numbered 
line—the line to branch to in the event of an error. 


Parameters: 
linenum The line to which you want BASICO9 to 
branch should an error occur. 
Notes: 


e ON ERROR GOTO is effective only with non-fatal, run- 
time errors. If such an error occurs without a preceding ON 
ERROR GOTO statement, BASICO9 enters the DEBUG 
mode. You must specify ON ERROR GOTO before an error 
occurs. 


e You turn on error trapping by specifying ON ERROR 
GOTO linenum. You turn off error trapping by specifying 
ON ERROR without a line number. 


@ Use ON ERROR GOTO with the ERR function (that 
returns the code of the last error) to specify a particular 
action for a particular error. You can also use ERROR to 
simulate an error to test error trapping. For more informa- 
tion on this, see ERROR. 
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Examples: 


ODIM FILENAME:STRING 

ODIM PATH: INTEGER 

1Q0INPUT "Name of file to create? ",FILENAME 
HOON ERROR GOTO 180 

OCREATE #PATH,FILENAME: UPDATE 

WEND 

1@@0PRINT "That file already exists...please 
choose another name..." 

GOTO 19 

LIEND 


Sample Program: 


If you created a directory file with the GET sample program, 
you can use this procedure to delete files from the original direc- 
tory using key characters. For instance, you might type XX as 
key characters. This means that any filename containing the 
character group XX is deleted. You can select any key characters 
you wish, but be sure they apply only to files you want to 
delete. 


If you want to delete all the files in the directory, type an aster- 
isk (*) when asked for key characters. 


This procedure uses ON ERROR to let the procedure continue, 
even if a directory entry cannot be deleted—if an entry is a sub- 
directory. Without the ON ERROR function, the procedure 
would produce an error and cease execution when it tried to 
delete a subdirectory. 


PROCEDURE purge 

OREM Use caution with this procedure 
OREM Be sure to specify key characters 
OREM that exist only in the files you 


OREM want to delete! 


ODIM PATH: INTEGER 

UDIM NAMEC188)9:STRING 

ODIM WILDCARD: STRING 

UX=@ 

DOPEN #PATH,“dirfile™:READ 
OWHILE NOTCEOFC#PATH)) DO 
UX=X+1 

UREAD #PATH,NAMECX) 


eee eee reer === 
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UENDWHILE 

UFOR T=1 TO X 
UPRINT NAMECT), 
LINES 7 


UFOR T=1 TO X 
UON ERROR GOTO 168 


THEN 


UDELETE NAMECT) 
UENDIF 

1OUNEXT T 

LEND 


1OOUPRINT "*O*Q*QERROR,O"; NAMECT); 


deleted...continuing."™ 
GOTO 18 
UEND 


BPRINT “DELETING *s- NAMECTI« © 2 


UINPUT “Wildcard Characters...",WILDCARD 


UIF SUBSTRCWILDCARD,NAMECT))>@ OR WILDCARD="«" 


"cannot be 
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ON/ GOSUB Jumps to subroutine on a 


specified condition 


Syntax: ON pos GOSUB linenum [,linenum,...] 


Function: Transfers procedure control to the line number 
located at position pos in the list of line numbers immediately 
following the GOSUB command. For example, if pos equals 1, 
BASICO9 branches to the first line number it encounters in 
the list. If pos equals 2, BASICO9 branches to the second line 
number it encounters in the list. If pos is greater than the 
number of items in the list, execution continues with the next 
command line. To use ON/GOSUB you must have numbered 
lines to match the line numbers in your list. End the routines 
accessed by ON/GOSUB with a RETURN statement. 


Parameters: 
pos An integer value pointing to a line number in 
a list of line numbers. 
linenum Any numbered line in the procedure. 
Examples: 


PRINT "You can now: (1) End the program C2) Print 
the results" 


PRINT ™ C3) Try again C4) Start 
a new program" . 
INPUT “Type The Jerter of your choice: * CHOICE 


ON CHOICE GOSUB 108, 200, 300, 408 
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Sample Program: 


This procedure uses MOD to execute repeatedly a sequence of 
( \ GOSUB commands. A loop of index of 80 causes execution to 
jump to each line number in the list 10 times. 


PROCEDURE repeat 

USHELL “TMODE -PAUSE" 

DIM TtINTEGER 

(FOR T=1 TO 8@ 

JON MODCT,8)+1 GOSUB 18,20,308,408,50,60,70,820 

UINEXT T 

USHELL “TMODE PAUSE™ 

UEND 
1BCIPRINT USING “Si07".4e™ \ RETURN 
2SLiPRiINT USING “S19*™, "sea" \ RETURN 
SUUPRINT USING "S1G*", "see \ RETURN 
4QUPRINT USING "S19", "Sexee" \ RETURN 
SOUPRINT USING "S1Q4", "xxxee" \ RETURN 
SQUPRINT USING: "STO." eeee" \ RETURN 
7OLUPRINT USING “S18°" “see™ \ RETURN 

om SOUPRINT USING. S71 G4"  “ee™ \ RETURN 
DEND 
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ON/ GOTO Jump to line number on a 


specified condition 


Syntax: ON pos GOTO linenum [,linenum,...| 


Function: Transfers procedure control to the line number 
located at position pos in the list of line numbers immediately 
following the GOTO command. For example, if pos equals 1, 
BASICO9 branches to the first line number it encounters in 
the list. If pos equals 2, BASICO9 branches to the second line 
number it encounters in the list. If pos is greater than the 
number of items in the list, execution continues with the next 
command line. To use ON/GOTO you must have numbered 
lines to match the line numbers in the list. 


Parameters: 
pos An integer value in a range from 1 to the 
number of items in the list following GOTO. 
linenum Any numbered line in the procedure. 
Examples: 


PRINT "You can now: (1) End the program (2) Print 
the results" 


PRINT " €3) Try again €4) Start 
a new program" 
ENPUL *lype The letter of your choice: " choice 


ON CHOICE GOTO 108, 200, 300, 408 


Sample Program: 


This procedure converts decimal numbers to binary. It uses ON 
GOTO to execute the operation you select from a menu: Convert 
a number, display the result of all conversions, or end the 
program. 


PROCEDURE bicalc 
ODIMONUMBER,NUM,X,STORAGE: INTEGER;UBI : STRING; 
DARRAYCS8@ ,2)9:STRING 

UCOUNT=9 
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1@UBI=""" \NUMBER=@8 \NUM=@ \X=@8 \STORAGE=@ 
UINPUT "Number to convert to binary '',NUMBER 
HIF NUMBER=@ THEN END 

DENDIF 

UNUM=LOG18CNUMBER)/.3 

UNUM=2*NUM \STORAGE=NUMBER 

DREPEAT 

UX=NUMBER/NUM 

UIF X>@ THEN BI=BI+'1" 
UNUMBER=MODCNUMBER ,NUM) 

ELSE BI=BI+'"g" 

DENDIF 

UNUM=NUM/2 

NUNTIL NUM<=1 

HIF NUMBER>@ THEN 

Upl=Ble"y" 

DELSE*BI=BI+"g" 

DENDIF 

UPRINT STORAGE: “" = “+ Bls ™ in binary." 
UPRINT 

NCOUNT=COUNT +1 

UARRAYCCOUNT ,1)=STR$CSTORAGE) 
UARRAYCCOUNT ,2)=BI 

T2ZUPRINT “Do you want to: €1) Convert another 
number." 

UPRINT “QOOOOOOOOUOOOO00¢ 2) Display all calculations 
thas far.” 

UPRINT “QOODODOOUOOOOOOOC3) End the program." 
DISPUT “Enter: 1. 2. of Sy. 0" schoice 

UON choice GOTO 10,280,380 

DEND 

COLUFOR T=1 TO COUNT 

UPRINT ARRAYCT,1)93; "™ = "s ARRAYCT,2) 
UNEXT T 

UGOTO 12 

SOUPRINT \ PRINT " Program Terminated" 
DEND 
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OPEN Opens a path to a device 


Syntax: OPEN #path,“pathlist” [access mode]|{ + access 
mode|[ +...] 


Function: Opens an input/output path to a disk file or to a 
device. When you open a file, you can select one or more of the 
following access modes: 


Mode 
READ 
WRITE 
UPDATE 
EXEC 


DIR 


Parameters: 


path 
pathlist 


access mode 


11-104 


Function 


Lets you read (receive) data from a file or 
device but does not allow you to write (send) 
data. 


Lets you write data to a file or device but does 
not allow you to read data. 


Lets you both read from and write to a file or 
device. 


Specifies that the file you want to access is in 
the current execution directory. 


Specifies that the file you want to access is a 
directory-type file. 


The variable in which BASICO9 stores the 
number of the newly opened path. 


The route to the file or device to be opened, 
including the filename if appropriate. 


The type of access the system is to allow for 
the file or device. Use a plus symbol to specify 
more than one type of access. 
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Notes: 


@ The access mode defines the direction of I/O transfers. 


‘aa 


@ Because OS-9 files are byte-addressed and are unformat- 
ted, you can set up the filing system you want for a partic- 
ular application. Your system can read the data contained 
in a file as single bytes or in groups of any size you want. 


@ You can expand a file using PRINT, WRITE, or PUT state- 
ments to write beyond the current end-of-file. | 
Examples: 
UPEN #1 RANS, “transportation sUPDATE 
OPER #SPuck ."7uger4/ report WRITE 


OPEN #OUTPATH,name$:UPDATE+EXEC 


Sample Program: 


cy This procedure opens a path to both the SYS directory on Drive 
/DO and the error message file. 


PROCEDURE readerr 

UDIM A:STRING[8@] 

UDIM PATH: BYTE 

OPEN #PATH,"/D9/SYS/ERRMSG": READ 
TIWHILE EOF C#PATHI<> TRUE DO 

UREAD #PATH,A 

LIPRINT A 

HENDWHILE 

OCLOSE #PATH 

WEND 
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OR Performs a Boolean OR operation 


Syntax: operand! OR operand2 


Function: Performs an OR operation on two or more values, 
returning a Boolean value of either TRUE or FALSE. 


Parameters: 


operand] Either numeric or string values. 
operand2 


Examples: 
PRINT A>3 OR B>3 


PRINT AS#™"YES™ or BSa"YES" 
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Sample Program: 


This procedure asks you to type a word or phrase, then converts 

ef all lowercase characters to uppercase. It uses OR to test for a 
character in your word or phrase that is outside of the ASCII 
values for lowercase letters. If it is, the character does not need 
converting. 


PROCEDURE uppercase 
UDIM PHRASE ,NEWSTRING:STRING[I8@1]; CHARACTER: 
SUTRINGE1 Is TyX2 INTEGER 
UNEWSTRING=""' \PHRASE="" 
PRINT "Type a phrase in lowercase and I will make 
it. uppercase.” 
LINPUT PHRASE 
FOR T=1 TO LENCPHRASE) 
LUICHARACTER=MID$CPHRASE,T,1) 
UX=ASCCCHARACTER) 
OIF X<97 OR X9122 THEN 
UNEWSTRING=NEWSTRING+CHARACTER 
LELSE 

LX=X-32 
, UNEWSTRING=NEWSTRING+CHR$CX) 
LIENDIF 
NEXT T 
UIPHRASE=NEWSTRING 
UNEWSTRING=""! 
UPRINT PHRASE 
HEND 
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PARAM Establishes variables to receive from 
another procedure 


Syntax: PARAM variablel,...][:typell;variablelf,...][:typel 
Evil 


Function: Defines the parameters that a called procedure 
expects to receive from the procedure that calls it. When 
using PARAM, be sure that the total size of each parameter 
in the calling procedure’s RUN statement is the same as the 
defined size in the called procedure’s PARAM statement. 


Parameters: 
variable A simple variable, an array structure, or a 
complex data structure. 
type Byte, Integer, Real, Boolean, String, or user 
defined. 
Notes: 


e BASICO9 checks the size of each parameter to prevent acci- 
dental access to storage other than that assigned to the 
parameter. However, BASICO9 does not check that parame- 
ters are of the proper type. In most cases you must be sure 
that types evaluated in RUN statements match the types 
defined in the PARAM statements. 


However, because BASICO9 does not perform type checking, 
it is possible to perform useful but normally illegal type 
conversions of identically-sized data structures. For example, 
you could pass a string of 80 characters to a procedure 
expecting a byte array of 80 elements. Each character in 
the string is assigned a corresponding position in the 
array. 


@ You declare simple arrays by using the variable name, 
without a subscript, in a PARAM statement. 
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@ You can declare several variables of the same type by sepa- 
rating them with commas. To separate variables of differ- 
ent types, follow each type group with a colon, the type 
name, and then a semicolon. 


e If you do not include a maximum length for a string vari- 
able enclosed in brackets following the type, like this: 


DLE Tames Ss tri ngtes) 


BASICO9 uses a default length of 32 characters for strings. 
You can declare shorter or longer lengths, to the capacity of 
BASICO09’s memory. 


@ Arrays can have one, two, or three dimensions. The 
PARAM format for dimensioned arrays is the same as for 
simple variables except you must follow each array name 
with a subscript, enclosed in parentheses, to indicate its 
size. The maximum array size is 32767. 


Arrays can be either of the standard BASICO9 type, or of a 
user-defined type. To create your own data types for simple 
variables, arrays, and complex data structures, see TYPE. 


Examples: 


PARAM NUMBER: INTEGER 


PARAM NAMESSTRING(I CS] ;ADDRESS# STRING LSE Is 21P x 
INTEGER 


PARAM NOT Ne, NOS? REAL s NO4 NOS. NOG: INTEGER: NO7: 
BY VE 


Sample Program: 


The first procedure asks you to enter a decimal number. Then, it 
asks you to choose whether you want to convert the number to 
binary or hexadecimal. Depending on your choice, the procedure 
calls (using RUN) either a procedure named Binary or a proce- 
dure named Hex. It passes the number you typed to the appro- 
priate procedure for conversion. 
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PROCEDURE convert 

UDIM NUMBER,CHOICE: INTEGER 

PRINT USING “SO8*"; “Hexadecimal - Binary 
Conversion Program" 

LIPRINT 

19@0JINPUT “Number to convert...'',NUMBER 

OIF NUMBER=98 THEN 

WIEND 

ENDIF 

UINPUT “Choose: (1) Binary or €2) Hex...";CHOICE 
HON CHOICE GOTO 286,38 

2B@URUN BINARY CNUMBER) 

GOTO 18 

3@URUN HEXCNUMBER) 

UGOTO 18 

WEND 


PROCEDURE binary 

UDIM NUM,X,STORAGE: INTEGER; BI:STRING; 
ARRAYCS@,2):STRING 

LIPARAM NUMBER: INTEGER 
UCOUNT=2 

UBI="" \NUM=@ \X=8 \STORAGE=9 
UNUM=LO0G18CNUMBER)/.3 
UNUM=2*NUM \STORAGE=NUMBER 
UREPEAT 

UX=NUMBER/NUM 

OIF X>@ THEN 

DptaBs ia" 
ONUMBER=MODCNUMBER , NUM) 

ELSE 

UBI=BI+"g" 

HENDIF 

LINUM=NUM/e2 

UUNTIL NUM<=1 

OIF NUMBER>@ THEN 

WBI=B ie." 

VEGSE 

UBI=BI+"g" 

LIENDIF 

UPRENT STORAGE: -** «°° By" in binary.” 
UPRINT 

LIEND 
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PROCEDURE hex 

UDIM NUM,X,STORAGE: INTEGER; TABLE,HX:STRING; 
ARRAYCS@,2):STRING 

LIPARAM NUMBER: INTEGER 
UTABLE="123456789ABCDEF" 
UHX=""*"¥ \NUM=@8 \X=8@ \STORAGE=28 
UINUM=LOG18CNUMBER)/1.2 
UNUM=16*NUM \STORAGE=NUMBER 
UREPEAT 

UX=NUMBER/NUM 

OIF X>@ THEN 
HIHX=HX+MID$CTABLE,X,1) 
UINUMBER=MODCNUMBER ,NUM) 

HELSE HX=HX+"g" 

ENDIF 

LINUM=NUM/16 

UUNTIL NUM<=1 

IF NUMBER>@ THEN 
UHX=HX+MID$CTABLE ,NUMBER,1) 
ELSE 

LIHX=HX+""g" 

LIENDIF 

OPRINT STORAGE; “" = ": HX: " in hexadecimal." 
LIPRINT 

WIEND 
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PAUSE Suspends execution and enters Debug 


Syntax: PAUSE text 


Function: Suspends the execution of a procedure and causes 
BASICO09 to enter the DEBUG mode. If you include text with 
the PAUSE command, it is displayed on the screen. 


Place PAUSE statements in a program temporarily to observe 
the way in which the procedure operates and to track down 
programming errors. When the procedure is operating cor- 
rectly, remove the PAUSE statement. 


After using DEBUG, you can continue execution of the paused 
procedure with the CONT command. 


Parameters: 
text A message you want PAUSE to display on the 
screen when BASICO9 executes the statement. 
Examples: 
PAUSE 


PAUSE The array is now full. 
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P EEK Returns the value in a memory location 


co” 

Syntax: PEEK(mem) 

Function: Returns the value of a memory byte as a decimal 
integer. The value returned is in the range 0 to 255. PEEK is 
the complement of the POKE statement. 

See also ADDR. 

Parameters: 

mem An integer value representing the location of 
the memory byte you want to examine. The 
memory byte is relative to the current pro- 
cess’s address space. 

Examples: 

‘= PRINT PEEKC15250@) 
MEMVAL = PEEKC4450@) 
- 
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Sample Program: 


This procedure asks you to type a phrase in uppercase charac- 
ters. It then uses ADDR to locate the area in memory where 
BASICO9 stores the phrase. Next, it reads each character from 
memory with PEEK, converts it to lowercase if necessary, and 
pokes the new value back into the same location. When the pro- 
cedure displays the contents of the phrase, it is all lowercase. 


PROCEDURE lowercase 

DIM LOC, TeINTEGER: PHRASE:STRINGLSO) 

OPRINT “Type a phrase in UPPERCASE and I[’11 make 
it lowercase." 

HINPUT PHRASE 

ULOC=ADDRCPHRASE ) 

OFOR T=LOC TO LOC+LENCPHRASE ) 
LX=PEEKCT) 

HIF X32 AND X<9O1 THEN 
UX=X+32 

UPGKE T,X 

LIENDIF 

UNEXT T 

PRINT PHRASE 


— 


LEND 
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P I Returns the value of pi 


Syntax: PI 


Function: Returns the constant value 3.14159265. 
Parameters: None 


Examples: 


PRINT "The area of a circle with a radius of 6 
inches is ™:PI#*#6*2 


Sample Program: 


This procedure uses the formula (PI+2)/15 as a basis for calcu- 
lating a screen position. Taking the sine of the formula, it prints 
a sine wave of asterisks down the screen. 


PROCEDURE picalc 

DIM FORMULA,CALCULATE,POSITION:REAL 
USHELE “DISPLAY gC" 
UFORMULA=CPI+2)/15 
UCALCULATE=FOQRMULA 

USHELL “TMODE -PAUSE™ 

UFOR T=8 TO 1820 
LIICALCULATE=CALCULATE+FORMULA 
UPOSITION=INTCSINCCALCULATE)*10+16) 
UPRINT TABCPOSITION); ‘#* 

INERT 7 

SHELL. “TMODE PAUSE” 

LEND 


I AE SST A BIE ERIE TEE TE PE SE SOE DE TE SEI LOE HPS BI AE IRAE LE I PI OE A CERI EAE EEE 
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POKE Stores a value in a memory location 


Syntax: POKE mem,value 


Function: Stores a value at the specified memory address, rel- 
ative to the current process’s address space. Mem is an abso- 
lute address at which BASICO9 stores a byte type value. 
POKE is the complement of the PEEK statement. 


You should use care when using POKE. Because it changes 
the value in memory, a POKE to the wrong portion of memory 
could cause OS-9, BASICO9, or your procedures to malfunction 
until you reboot the system. 


See also ADDR. 


Parameters: 
mem An integer value representing the location of 
the memory byte you want to change. 
value The value to store in the specified memory 
location. 
Examples: 


PORE- Loeoe gil 
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Sample Program: 


This procedure asks you to type a phrase in uppercase charac- 
ters. It then uses ADDR to locate the area in memory where 
BASICO9 stores the phrase. Next, it reads each character from 
memory, converts it to lowercase if necessary, and uses POKE to 
store the new value back in the same location. When the proce- 
dure next displays the contents of the phrase, it is all lowercase. 


PROCEDURE lowercase 

UDIM LOC,T: INTEGER; PHRASE:STRING[8@] 

UPRINT “Type a phrase in UPPERCASE and I’1l make 
it lowercase." 

HINPUT PHRASE 

PILOC=ADDRCPHRASE ) 

FOR T=LOC TO LOC+LENCPHRASE) 
UIX=PEEKCT) 

HIF X>32 AND X<91 THEN 
UX=X+32 

OPOKE Tax 

WENDIF 

UNEXT T 

LIPRINT PHRASE 

WEND 


SS ESS RP TSS SE (I TS ERI SP I SF I ES ES RT EE EO REET 
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POS Returns cursor’s column position 


Syntax: POS 


Function: Returns the current column position of the cursor. 
Parameters: None 


Examples: 
PRINT POS 


Sample Program: 


This procedure is a simple typing program that uses POS to 
make sure that words are not split when you type to the end of 
the screen. After you type 25 characters on a line, the procedure 
breaks the line at the next space character. 


PROCEDURE wordwrap 
DIM CHARACTER: STRING[1] 


JIPRINT USONG “Ss2°"s "Word Wrap Program” 
PRINT USING “S32""s “Press [CTRLILC] to Exit” 
UPRINT 

TISHELL. *TMODE -ECHO™ 

OWHILE CHARACTER<>" " DO 

GET #1,CHARACTER 

UPRINT CHARACTER; 

OIF POS>25 AND CHARACTER="" " THEN 
LIPRINT CHR$C13) 

VEN ELF 
DENDWHILE 


SHELL. “TMODE. ECHO” 
LEND 
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PRIN T Displays text 


Syntax: PRINT [#path] [TAB(pos);] datal;data...] 


Function: Prints numeric or string data on the video display 
unless another path is specified. 


Parameters: 


path 


pos 


data 


Notes: 


The number corresponding to an opened device 
or file. If you do not specify path, the default 
is #1, the video screen (standard output 
device). To print to another device or file, first 
OPEN a path to that file or device (see 
OPEN). 


A column number that tells TAB where to 
begin printing. Specify any number from 0 to 
the width of your video display. 


Any numeric or string constant or variable. 
Enclose string constants within quotation 
marks. All data items must be separated by a 
semicolon or comma. 


@ If you specify more than one data item in the statement, 
separate them with commas or semicolons. 


e If you use commas, PRINT automatically advances to the 
next tab zone before printing the next item. In BASICO9, 
tab zones are 16 characters apart. 


e If you use semicolons or spaces to separate data items, 
BASICO9 prints the items without any spaces between 
them. BASICO9 begins the next print item immediately fol- 
lowing the end of the last print item. 


e If you end a print item without any trailing punctuation, 
PRINT begins printing at the beginning of the next line. 
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If the data being printed is longer than the display screen 
width, PRINT moves to the next line and continues print- 
ing the data. 


TAB causes BASICO9 to begin displaying the specified data 
at the column position specified by TAB. If the output line 


is already past the specified TAB position, PRINT ignores 
TAB. 


You can concatenate items for printing using the plus (+) 
symbol, for example: print “hello "+name$+" " 
+lastname$. 


PRINT displays REAL numbers with nine or fewer digits 
in regular format. It displays REAL numbers with more 
than nine digits in exponential format. For example, 
1073741824 is displayed as 1.07374182E+99. 


You must enclose string constants within quotation marks. 


Examples: 


PRINT A$ 


PRINT "Menu Items" 


PRINT COUNT 


PRINT VALUE,TEMP+(€n/2.5),LOCATIOQONS 


PRINT #PRINTER_PATH,"The result is ";NUMBER 


PRINT #OUTPATH FMT$,COUNT,VALUE 


PRINT “what iS” *NAaMese'’s eager “> 


PRINT “INDEX+ “st sTABCeS)<"VALUE® “eVOLUE 
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Sample Program: 


This procedure asks you to type a word or phrase, then displays 
it backwards by reading each character from end to beginning 
and using PRINT to display it on the screen. 


PROCEDURE reverse 

UDIM PHRASE,TITLE:STRING; T,BEGIN: INTEGER 

UDIM INSTRUCTIONS: STRING[43] 

UTITLE="Word Reversing Pregram™ 
HINSTRUCTIONS="Type a word or phrase you want to 
reverse: " 

UPRINT TLE 

De Ds ec eee 

UWHILE PHRASE<>"" DO 

LIPRINT 

UPRINT INSTRUCTIONS 

UWINPUT PHRASE 

(IBEGIN=LENCPHRASE ) 

UPRINT “This is how your phrase looks backwards:"™ 
FOR T=BEGIN TO 1 STEP -1 

PRINT MID$CPHRASE,T,1); 

UNEXT T 

PRINT 

HENDWHILE 

LIEND 
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PRINT USING Displays formatted text 


Syntax: PRINT [#path] USING [format,] data|;data...] 


Function: Prints data using a format you specify. This state- 
ment is especially useful for printing report headings, 
accounting reports, checks, or any document requiring a spe- 
cific format. USING is actually an extension of the PRINT 
statement; therefore, the same rules that apply to the PRINT 
statement also apply to the PRINT USING statement (see 


PRINT). 


Parameters: 


path 


format 


data 


Notes: 


The number corresponding to an opened device 
or file. If you do not specify path, the default 
is #1, the video screen (standard output 
device). To print to another device or file, first 
OPEN a path to that file or device (see 
OPEN). 


An expression specifying the arrangement of 
the displayed data. 


Any numeric or string constant or variable. 
Always enclose string constants within quota- 
tion marks. Each data item must be separated 
by semicolons or commas. 


Each PRINT USING format specifier begins with a single identi- 
fier letter that specifies the type of format, as shown in the fol- 


lowing table: 


Amman 


Boolean format 
exponential format 
hexadecimal format 
integer format 

real format 

string format 
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Follow the identifier letter with a constant number that specifies 
the field width. This number indicates the exact number of print 
columns the output occupies. It must allow for both the data and 
any overhead characters, such as sign characters, decimal points, 
exponents, and so on. 


Optionally, you can add a justification indicator to the format 
expression. The indicators are <, >, and *. The meaning of these 
indicators varies, depending on the format type in which you use 
them. See the format type descriptions for specific information. 


Note: Do not use any spaces within format expressions. 
The following are the format type descriptions: 
Real 


_ Use this format for real, integer, or byte type numbers. The total 
field width specification must include two overhead positions for 
the sign and decimal point. The field width has two parts, sepa- 
rated by a period. The first part specifies the integer portion of 
the field. The second part specifies how many fractional digits to 
display to the right of the decimal point. 


If a number has more significant digits than the field allows, 
BASICO9 uses the undisplayed digits to round the number 
within the correct field width. 


The justification modes are: 


< Left justify with leading sign and trailing spaces. This is 
the default if you omit a justification indicator. 


> Right justify with leading spaces and sign. 


a Right justify with leading spaces and trailing sign 
(financial format). 


Some examples and their results are: 


PRINT USING “RS. 2<", 5678. 123 so 7S. be 
PROAT. USING “Re.22".567/5.123 "6/82 
PRIN] OSING *REc2e" 12.3 Zee 
PREM USING “RE. 29". +5559 +S so" 


PRINT USING “R1@.2°".=6722.4599 6722.46- 
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Exponential 


Use this format to display real, integer, or byte values in the sci- 
entific notation format—using a mantissa and decimal exponent. 
The field has two parts: the first part must allow for six overhead 
positions for the mantissa sign, decimal point, and exponent 
characters. 


The justification modes are: 


< Left justify with leading sign and trailing spaces. This is 
the default if you omit a justification indicator. 


> Right justify with leading spaces and sign. 


Some examples and their results are: 


PRINT USING. “E12. 3"; 1234.367 1, 235E +83 

PRINT USING "E13.6>",-.001234 -1.234000E-03 

PRINT USING: "£16.59", 123456769 1,23457E+98 
Integer 


Use this format to display integer, byte, or real type numbers in 
an integer or byte format. The field width must allow for one 
position of overhead for the sign. 


The justification modes are: 


< Left justify with leading sign and trailing spaces. This is 
the default if you omit a justification indicator. 


> Right justify with leading spaces and sign. 
. Right justify with leading sign and zeroes. 
Some examples and their results are: 


PRINT USING *14<" 18 10 
FRING USING “Las” 218 10 
PRINT USinG. “14-18. =279 


Hexadecimal 


Use this format to display any data type in hexadecimal nota- 
tion. The field width specification determines the number of 
hexadecimal characters BASICO9 displays. If the data to display 
is string type, this function displays the ASCII value of each 
character in hexadecimal. 
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The justification modes are: 


< Left justify with trailing spaces. This is the default if 
you omit a justification indicator. 


> Right justify with leading spaces. 
* Center digits. 


The number of bytes of memory used to represent data varies 
according to data type. The following chart suggests field widths 
for specific data types: 


Memory Field Width 
Type Bytes To Specify 
Boolean and Byte 1 Z 
Integer 2 4 
Real 5 10 
String 1 per 2 times the string 
character length 


Some examples and their results are: 


PRINT USING “H4" 196 0064 
PRET USiNG: “Hat* =] Pree 
PRINT USING "H8“", "ABC" 414243 


String 


Use this format to display string data of any length. The field 
width specifies the total field size. If the string to display is 
shorter than the field size, PRINT USING pads it with spaces 
according to the justification mode. If the string to display is 
longer than the specified field width, PRINT USING truncates 
the right portion of the string. 


The justification modes are: 


< Left justify with trailing spaces. This is the default if 
you omit a justification indicator. 


> Right justify with leading spaces. 


a Center characters. 
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Some examples and their results are: 


PRINT USING “S9<","HELLO” HELLO 

PRINT USING "S9>","HELLO”™ HELLO 

PRINT USING ™“S9*", “HELLO” HELLO 
Boolean 


Use this format to display Boolean expression results. BASICO9 
converts the result of the expression to the strings “True” or 
“False.” The format and results are identical to STRING formats. 
The justification modes are: 


< Left justify with trailing spaces. This is the default if 
you omit a justification indicator. 


> Right justify with leading spaces. 
« — Center characters. 
If A=5 and B=6, some examples and their results are: 


PRINT USING “Bet A<B True 
PRINT USING “BS2", AS False 
PRINT USENG- "BS*". A285 False 


Control Specifiers 


You can also use control specifiers within PRINT USING for- 
mats. The three specifiers are: 


Tn Tab. n specifies a tab column at which to display 
the next data. 

Xn Spaces. n specifies a number of spaces to insert. 

‘text Constant string. text is a string that is constant to 
the format. 


An example and its result is: 


PRINT USING "’Address’ ,X1,H4,X4, ‘Data’ ,X1,He", 
1000,1080 


Address @3E8 Data 64 
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Repeat 


You can repeat identical sequences of specifications using paren- 
theses within a format specification. Enclose the group of speci- 
fications you wish to repeat, preceded by a repetition count, such 
as: 


"2€X2,r10.5)" in place of "X2,R10.5,X2,R10.5" 


“2CT242€%1 59499" In place of "12.%1,54,%1 484, 12,X1, 
245,414,854" 


Sample Program: 


This program looks at memory locations 32000 to 32010 and dis- 
plays their contents in decimal, hexadecimal, and binary. PRINT 
USING formats the display in columns. 


PROCEDURE memlook 

UDIM NUMBER,T,MEM,VALUE: INTEGER 

UDIM X,NUM: INTEGER; CHARACTER,BI:STRING 
LUPRINT "OAddr .QDec.QHex.0BinZLLUASCII" 
UFOR Z=32008 TO 320190 

(JBI = '008 

UINUMBER=PEEKC2Z) 

HIF NUMBER>@ THEN 

UIGOSUB 1809 

HENDIEF 

HIF PEEKCZ)<32 THEN 

LICHARACTER="" 

ELSE 

NCHARACTER=CHR$CPEEK(Z)) 

LIENDIF 

DIF PEEKCZ)>@ THEN 

UIPRINT USING LOR 4 17 51 Se XS. H4<, %15S8*,X2S551 "52. 
PEEKCZ),PEEKCZ),BI,CHARACTER 

WJELSE PRINT USING "Let. 174 14*,%25H4¢.% 1,86). X2, 
Si s250.80,"0900"," 

DENDIF 

LINEXT Z 

LIEND 
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189@0UNUM=L0OG18CNUMBER)/.3 
UNUM=2*NUM 

UREPEAT 

UX =NUMBER/NUM 

DIF X>2@ THEN Ble=B]4™1™ 
UNUMBER=MODCNUMBER , NUM) 
VELSE BileBlL?"a™ 

LENDIF 

UNUM=NUM/2 

OUNTIL NUM<=1 


HIF NUMBER>@ THEN 
UBl=Bie't™ 
VELSE Bl=Bi+"e” 
END Le 


URETURN 
LEND 
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P UT Writes to a direct access file 


Syntax: PUT #path,data 


Function: Writes a fixed-size binary data record to a file or 
device. Use PUT to store data in random access files. 


Although you usually use PUT with files, you can also use it 
to send data to a device. 


For information about storing data in random access files, see 
Chapter 8, “Disk Files”. Also, see GET, SEEK, and SIZE. 


Parameters: 
path A variable name you chose to use in an OPEN 
or CREATE statement that stores the number 
of the path to the file or device to which you 
are directing data. 
data Kither a variable containing the data you 
want to send or a string of data. 
Examples: 


PUT #PATH,DATA$ 
PUT INPUT ,ARRAY$ 


Sample Program: 


This procedure is a simple inventory data base. You type in the 
information for an item name, list cost, actual cost, and quan- 
tity. Using PUT, the procedure stores data in a file named 
Inventory. 


PROCEDURE inventory 

UTYPE INV_ITEM=NAME:STRING(L25]; LIST,COST:REAL; 
QTY: INTEGER 

JIDIM INV__ARRAYC108):INV_ITEM 

UDIM WORK__REC: INV_ITEM 

DIM PATH:BYTE 

HON ERROR GOTO 18 
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ODELETE “inventory” 

1800N ERROR 

DCREATE #PATH,"inventory"™ 
UWORK__REC.NAME="""" 
OWORK__REC.LIST=9 
OWORK__REC.COST=90 
DOWORK__REC.QTY=@ 

OFOR N=1 TO 100 

OPUT #PATH,WORK__REC 
ONEXT N 

OLOOP 

DINPUT “Record number? ",recnum 
OIF recnum<1 OR recnum>1@@ THEN 
OPRINT 

OPRINT “End of Session" 

OPRINT 

OCLOSE #PATH 

DEND 

DENDIF 

OINPUT "Item name? ",WORK__REC.NAME 
OINPUT “List price? ",WORK_REC.LIST 
OINPUT “Cost price? ™,WORK_REC.COST 
OINPUT “Quantity? "™,WORK_REC.QTY 
OSEEK #PATH,Crecnum-1)*SIZECWORK_REC) 
OPUT #PATH,WORK__REC 

DENDLOOP 

END 
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RAD Returns trigonometric calculations in 
radians 


Syntax: RAD 


Function: Set a procedure’s state flag so that a procedure uses 
radians in SIN, COS, TAN, ACS, ASN, and ATN functions. 
Because this is the BASICO9 default, you do not need to use 
the RAD statement unless you previously used a DEG state- 
ment in the procedure. 


Parameters: None 


Examples: 
RAD 


Sample Program: 


This program calculates sine, cosine, and tangent for a value you 
supply. It calculates one set of results in degrees, using DEG, 
and the second set of results in radians using RAD. 


PROCEDURE trigcalc 
UDIM ANGLE:REAL 


LIDEG 

UINPUT “Enter the angle of two sides of a 
triangle sa.” ANGLE 

UPRINT 


PR IRT “LOCCAnte bet." StNe” COSINE”, "Tan 
OPRINT “(UDU---------------------------------- 


UPRINT “Degrees = "; ANGLE,SINCANGLE),COSCANGLE), 
TANCANGLE 9 

URAD 

UPRINT “Radians = "; ANGLE,SINCANGLE),COSCANGLE), 
TANCANGLE ) 

UPRINT 

END 
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RE AD Reads data from a device or DATA 


statement 


Syntax: READ [#path,] varname 


Function: Reads either an ASCII record from a sequential file 


or device, or an item from a DATA statement. 
Parameters: 
path A variable containing the path number of the 
file you want to access. You can also specify 
one of the standard I/O paths (0, 1, or 2). 
varname The variable in which you want to store the 
data read from a file, device, or DATA line. 
Notes: 
The following information deals with reading sequential disk 
files: 
@ To read file records, you must first dimension a variable to 


contain the path number of the file, then use OPEN or 
CREATE to open a file in the READ or UPDATE access 
mode. The command begins reading records at the first 
record in the file. After it reads each item, it updates the 
pointer to the next item. 


Records can be of any length within a file. Make sure the 
variable you use to store the records is dimensioned large 
enough to store each item. If the variable storage is too 
small, BASICO9 truncates the record to the maximum size 
for which you dimensioned the variable. If you do not indi- 
cate a variable size with the DIM statement, the default is 
32 characters. 


BASICO9 separates individual data items in the input 
record with ASCII null characters. You can also separate 
numeric items with comma or space character delimiters. 
Each input record is terminated by a carriage return 
character. 
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The following information deals with reading DATA items: 


@ READ accesses DATA line items sequentially. Each string 
a type item in a DATA line must be surrounded by quotation 
marks. Items in a DATA line must be separated with 

commas. 


@ Each READ command copies an item into the specified 
variable storage and updates the data pointer to the next 
item, if any. 


@ You can independently move the pointer to a selected DATA 
statement. To do this, use line numbers with the DATA 
lines See the DATA and RESTORE commands for more 
information on using this function of READ. 

Examples: 
READ #PATH,DATA 
READ #1,RESPONSE$ 


BEAD # INPUT, [NDEXCX 


FOR T=1 TO 18 

READ NAMES$CT) 

NEAT T 

Date oD sO Ue TENA WENDY 

Date. “SeEL™ MICKIE’ 4" P RED." MARV» WINN DE 
rf 
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Sample Program: 


This procedure puts random values between 1 and 10 into a disk 
file, then READS the values and uses asterisks to indicate how 
many times RND selected each value. 


PROCEDURE randlist 
OUDIM SHOW,BUCKET:STRING 
DIM T,PATH,SELECTC18),R: INTEGER 


BUCKET He eR HHH KKH HEHEHE HEHEHE HEHEHE HEN 
UFOR T=1 TO 10 

USELECTCT)=@ 

ONEXT T 

DON ERROR GOTO 19 

USHELL “DEL -RANDF PLE: 

18U0N ERROR 

DCREATE #PATH,"randfile™:UPDATE 
UFOR T=1 TO 108 

UR=RNDC9)+1 

OWRITE #PATH,R 

NEAT. T 

OPRINT “Random Distribution” 
OSEEK #PATH,@ 

UFOR T=1 TO 100 

OREAD #PATH,NUM 
OSELECTCNUM)=SELECTCNUM) +1 

ONEXT T 

LIFOR T=1 TO 18 

OUSHOW=RIGHT$CBUCKET ,SELECTCT)) 

PRINT USING “S6<, [3¢.S2<,s20<" “Number”; 
tao 2". SRR 

UINEX TT 

OCLOSE #PATH 

LEND 
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REM Inserts remarks in a procedure 


Syntax: REM [text] 
(* [text][*)] 


Function: Inserts remarks inside a procedure. BASICO9 
ignores these remarks; they serve only to document a proce- 
dure and its functions. Use remarks to title a procedure, show 
its creation date, show the name of the programmer, or to 
explain particular features and operations of a procedure. 


Parameters: 
text Comments you want to include within a 
procedure 
Notes: 


® You can insert remarks at any point in a procedure. 


@ The second form of REM, using parentheses and asterisks, 
is compatible with Pascal programming structure. 


@ When editing programs, you can use the exclamation char- 
acter “!” in place of the keyword REM. 


@ BASIC09’s initial compilation retains remarks, but the 
PACK compile command strips them from procedures. 
Examples: 
REM this is a comment 


C* Insert text between parentheses and 
asterisks*) 


C* or use only one parenthesis and asterisk 
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Sample Program: 


This procedure uses the various forms of REM to explain its 
operations. 


PROCEDURE copydir 

OREM Use this program with the 
L(+ GET sample program to +*) 

L(+ create a file of directory+) 
L(+ filenames, then copy the*) 
[(+ files to another directory#) 

CIDIM PATH, T,COUNT: INTEGER; FILE, JOB,DIRNAME:STRING 

KIOPEN #PATH,"dirfile":READ (* open the file 

KIINPUT "Name of new directory...",DIRNAME (# get the directory 
DSHELL "MAKDIR "+DIRNAME (# create a newdirectory 

LISHELL "LOAD COPY" 


KIWHILE NOTCEOFC#PATH)) DO 


LIREAD #PATH, FILE (* get a filename 


CJOB=FILE+" "+DIRNAME+"/"+FILE (# create the COPY syntax 
LION ERROR GOTO 10 

LIPRINT "COPY "; JOB (* display the operation 

LISHELL "COPY "+JOB (# copy the file 

18LJ0N ERROR 

LIENDWHILE 

OCLOSE #PATH 

LIEND 
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REPEAT/UNTIL 


Establishes a loop/Terminates on specified condition 


Syntax: REPEAT 
procedure lines 
UNTIL expression 


Function: Establishes a loop that executes the encompassed 
procedure lines until the result of the expression following 
UNTIL is true. Because the loop is tested at the bottom, the 
lines within the loop are executed at least once. 


Parameters: 
expression A Boolean expression (returns either True or 
False). 
procedure Statements you want to repeat until expression 
lines returns False. 
Examples: 
REPEAT 


COUNT = COUNT+1 
UNTIL COUNT > 1808 


INPUT -X 5 ¥ 

REPEAT 

X = X-1 

¥ 2 ¥=7 

UNTIL x*<1 OR Y<P 
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Sample Program: 


The procedure sorts a disk file. In this case, it is written to sort 
the diskfile created by the GET sample program—a directory 
listing. It uses a REPEAT/UNTIL loop to compare a string in 
the file with the first string in the file. If the first string is 
greater than the comparison string, the procedure swaps them. 


PROCEDURE dirsort 

DIM BIrEMP:BOGLEANs. TEMP ,FILESCT2S) =STRINGs TOP, 
BOTTOM,M,N: INTEGER 

DIM T,X,PATH: INTEGER 

UFGR T=? TO F2s 

PE LLESeT a=" 


REAL. 


UT =@ 


CUOPEN #PATH, “oirt rie sKEAD 


PRINT “LOADING: 


OWHILE NOTCEOFC#PATH)) DO 
T=T+1 

READ #PATH,FILESCT) 
OENDWHILE 

OTOP=T 

OBOTTOM=1 

OPRINT "SORTING: "; 


18UN=BOTTOM 

LUM=TOP 

UPR INE es 

ULOOP 

REPEAT 

DBTEMP=F ILESCNI<FILESCTOP? 
LIN=N+1 

HUNTIL NOTCBTEMP) 
UN=N-1 

HEXITIF N=M THEN 
UENDEXIT 


LUITEMP#FILESCM) 
UF PLES CM Jer ILESCND 
UFILESCN)=TEMP 
LIN=N +1 

UEXITIF N*M THEN 


UENDEXIT 
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UENDLOOP 

LIF N<>TOP THEN 

ULE FILESCNd<>F TLESCTOPD THEN 
UTEMP=SF TLESCN? 

JF ILESCND =F ILESCTOP) 

UF LLESC TOP) =TEMP 

UENDIF 

JENDIF 


UIF BOTTOM<N-1 THEN 
UTOP=N-1 

UGOTO 18 

END: 

ULE Nee OP THEN 
UBOTTOM=N+1 

UGOTO 10 

DEADI F 

UCLOSE #PATH 

UPELETE ““dirtile™ 
UICREATE #PATH,"“dirfile™:WRITE 
LPRINT 

UFUR 2%) ToT 

UWRITE #PATH,FILESCZ) 
HPRINT FILESCZ). 

URE XT 2 


UCLOSE #PATH 
UEND 
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RESTORE Resets READ pointer 


Syntax: RESTORE linenumber 


Function: Sets the pointer for the READ command to the 
specified line number. RESTORE without a line number sets 
the data pointer to the first data statement in the procedure. 


READ assigns the items in a DATA statement to variable 
storage. When you read an item, the pointer automatically 
advances to the next item. Using RESTORE you can skip 
backward or forward to data items at a specific line number. 


Parameters: 
linenumber The line number of the DATA items you want 
READ to access next. 
Examples: 


RESTORE: 180 


Sample Program: 


This procedure draws a box on the screen. It uses RESTORE to 
repeat the data in line 20 to create the sides of the box. 


PROCEDURE box 

DDIM: LINE 2S TRING 

UREAD LINE 

PRINT 2DNE 

FOR T=4 70 19 

URESTORE 20 

DREAD LINE 

WPRIST. DAE 

UINEXT 7 

URESTORE 18 

JREAD LINE 

PRIA LENE 

1SGDATA A+ S83 eee See Sere aes ae 
290DATA ™QUOOUOCU0UCOUCCUCUUOOo" 
UEND 


RS EST EEL LEAST 
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RE TURN Returns from subroutine 


Syntax: RETURN 


Function: Returns procedure execution to the line immedi- 
ately following the last GOSUB statement. 


Every subroutine you access with GOSUB must contain a 
RETURN statement. You can call a subroutine in this man- 
ner aS many times as you want. 


Parameters: None 


Sample Program: 


This procedure draws a design of asterisks down the display 
screen. It uses MOD to send execution to a series of PRINT 
USING routines over and over. Each PRINT USING routine 
sends execution back to the main routine with a RETURN 
statement. 


PROCEDURE stars 

UDIM T:INTEGER 

USHELL. “TMODE =PAUSE” 

UFOR T=1 TO 100 

JON MODCT,8)+1 GOSUB 18,280,30,40,50,60,70,80 
UNEXT T 

SHELL “TMDDE PAUSE"™ 

WIEND 

1BUPRINT USING “S1tg*"."e™ \- RETURN 

2OUIPRINT USING “S1Oe%. "ae \ RETURN 

SOUPRINT USING “Sig, "eee" ) RETURN 
SQUPRINT USING “STG*", “eee” \ RETURN 
SBLUPRINT USING “S194 ,“steee™ \% RETURN 
SBUPRINT USTNG “S10*" “sees \. RETURN 
JOICRINT USING “SITUS. "eee \ RETURN 
SULUPRINT USING *S104"."ee"-% RETURN 
END 
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RIGHTS Returns specified rightmost portion 
of a string 


Syntax: RIGHTS(string,length) 


Function: Returns the specified number of characters from the 
right portion of the specified string. If length is the same as or 
greater than the number of characters in string, then RIGHTS 
returns all of the characters in the string. 


Parameters: 
string A sequence of string type characters or a vari- 
able containing a sequence of string type 
characters. 
length The number of characters you want to access. 
Examples: 


PRINT RLICHT SC’ ROTDOG™, 3) 


PRINT RIGHTS$CA$ ,6) 


Sample Program: 


PROCEDURE lastname 

UDIM NAMES:STRING; LASTNAME:STRING(190] 
UIPRINT “Here are the last names:" 
UFOR T=1 TO 18 

UREAD NAMES 

UPOINTER=SUBSTRC"™ "*,NAMES) 
UPOINTER=LENCNAMES)-POINTER 
ULASTNAME=RIGHT$CNAMES,POINTER) 


UPRINT LASTNAME 


UNEXT T 


DATA “Joe Blonski","Mike Marvel"™,"Hal Skeemish", 
“Tred Langly” 


UDATA "Jane Misty","“Wendy Paston",™Martha 
Upshong", "Jacqueline Rivers" 

DATA "Susy Reetmore","Wilson Creding"™ 
DEND 
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RN D Returns a random value 


Syntax: RND(number) 


Function: Returns a random real value in the following 
ranges: 


If number = 0 then range = 0 tol 
If number > 0 then range = 0 to number 


The values produced by RND are not truly random numbers, 
but occur in a predictable sequence. Specifying a number less 
than 0 begins the sequence over. 

Parameters: 


number A numeric constant, variable, or expression. 


Examples: 
PRINT RNDC5) 
PRINT RNDCA) 


PRINT RNDCA*5S) 


Sample Program: 


This procedure presents addition problems for you to solve. 
It uses RND to select two numbers between 0 and 20. 
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PROCEDURE addition 

ODIM A,B,ANSWER,C: INTEGER 
FOR T#t TH oS 

HA=RNDC28 ) 

UB=RNDC28) 

LC=A+B 

OPRINT USING “*’What iss*,132",A 
OPRINT USING "“’(UDUUU+t0’ ,13>",B 
PRINT “OE == " 

OINPUT “COOUUDLU", ANSWER 

HIF ANSWER=C THEN 

DPRINT “CORRECT” 
LIELSE 

OPRINT "WRONG" 
UENDIF 

UPRINT 

UNEXT T 


END 
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RUN Executes another procedure 


Syntax: RUN procname [(paran],param,...])] 


Function: Calls a procedure for execution, passing the speci- 
fied parameters to the called procedure. When the called pro- 
cedure ends, execution returns to the calling procedure, 
beginning at the statement following the RUN statement. 


RUN can calla procedure existing within the workspace, a 
procedure previously compiled by the PACK command, or a 
machine language procedure outside the workspace. 


Parameters: 
procname The name of the procedure to execute. The 
procname can be the literal name of the proce- 
dure to execute, or it can be a variable name 
containing the procedure name. 
param One or more parameters that the called pro- 
gram needs for execution. The parameters can 
be variables or constants, or the names of 
entire arrays or data structures. 
Notes: 
@ You can pass all types of data to a called program except 


byte type. However, you can pass byte arrays. 


If a parameter is a constant or expression, BASICO9 passes 
it by value. That is, BASICO9 evaluates the constant or 
expression and places it in temporary storage. It passes the 
address of the temporary storage location to the called pro- 
cedure. The called program can change the passed values, 
but the changes are not reflected in the calling procedure. 


If a parameter is the name of a variable, array, or data 
structure, BASICO9 passes it to the called program by ref- 
erence. That is, it passes the address of the variable storage 
to the called procedure. Thus, the value can be changed by 
the receiving procedure, and these changes are reflected in 
the calling procedure. 
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e If the procedure named by RUN is not in the workspace, 
BASICO9 looks outside the workspace. If it cannot find it 
there, it looks in the current execution directory for a disk 
file with the proper name. If the file is on disk, BASICO9 
loads and executes it, regardless of whether it is a packed 
BASICO9 program or a machine language program. 


If the program is a machine language module, BASICO9 
executes a JSR Gump to subroutine) instruction to its entry 
point and executes it as 6809 native code. The machine 
language program returns to the original calling procedure 
by executing a RTS (return from subroutine) instruction. 


e@ After you call an external procedure, and no longer need it, 
use KILL to remove it from memory to free space for other 
operations. 


@ Machine language modules return error status by setting 
the C bit of the MPU condition codes register, and by set- 
ting the B register to the appropriate error code. 


Examples: 


RUN CALCULATEC19@,20,ADD) 


RUN PRINTCTEXT$) 


Sample Program: 


Makelist creates and displays a list of fruit. Next, it asks you to 
type a word to insert. After you type and enter a new word, 
Makelist uses RUN to call a second procedure named Insert to 
look through the list and insert the new word in alphabetical 
order. After each insertion, the procedure asks for another word. 
Press only to terminate the program. 


PROCEDURE makelist 
ODIM LISTC25),NEWORD, TEMPWORD:STRING([15] 
UDIM T,EASTs INTEGER 

ULAST=19 

DPR This 2S your list sca 

OFOR T=1 TO LAST 

DREAD LISTCT) 

UPRENT LISTCT?s 

ONEXT T 

ULOOP 
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LIPRINT 

UPRINT 

UINPUT “Type a word to insert...",NEWORD 
HEXITIF NEWORD="" THEN 

LIPRINT 


WEND "I’ve ended the session at Vour PequeSst ey.” 
HENDEXIT 

URUN InsertCLIST,NEWORD,LAST) 

UPRINT 

OPRINT "This is your new list...™ 
LEFOR T=) 70 LAST 

PRINT LISTCTr? s 

ONEXT T. 

UPRINT 

HENDLOOP 

UDATA "APPLES", "BANANAS","CANTALOUPE" 
UDATA "DATES","GRAPES","LEMONS" 

DATA "MANGOS", "PEACHES", "PLUMS" 
UDATA "PEARS" 


PROCEDURE insert 

LPARAM LISTC€25),NEWORD:STRING([15] 
UIPARAM LAST: INTEGER 

UDIM TEMPWORD:STRING[15] 
UDIM T,X: INTEGER 

LIT = 1 

UWHILE NEWORD>LISTCT) DO 
UT=T+1 

HENDWHILE 

LIFOR X=T TO LAST 
UTEMPWORD=LISTCX) 
ULISTCX)=NEWORD 
UNEWORD=TEMPWORD 

LIN EEKT x 

ULAST=LAST+1 
ULISTCLAST)=NEWORD 

WEND 
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SEEK Resets the direct-access file pointer 


Syntax: SEEK #path,number 


Function: Changes the file pointer address in a disk file. The 
pointer indicates the location in a file for the next READ or 
WRITE operation. 


You usually use SEEK with random access files to move the 
pointer from one record to another, in any order. You can also 
use SEEK with sequential access files to rewind the pointer 
to the beginning of the file (to the first item or record). 


For information about storing data in random access files, see 
Chapter 8, “Disk Files.” Also see PUT, GET, and SIZE. 


Parameters: 
path A variable name you choose in which BASICO9 
stores the number of the path it opens to the WO 
file you specify. 
number The item or record number you want to access. 
If you are rewinding a sequential access file, 
specify a number of 0. 
Examples: 


SEEK #PATH,@ 
SEEK #OUTF ELE A 
SEEK #INDEX,LOCATION*SIZECINVENTORY ) 


Sample Program: 


This procedure creates a file named Test1, then writes 10 lines 

of data into it. Next, it reads the lines from the file and displays J 
them. It uses SEEK to both store and extract the lines in blocks 

of 25 characters. 
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PROCEDURE makelines 


DIM LENGTHS BY TE 


UDIM PATH:BYTE 
UGENGTHSeZs 
UIBASE 9g 

UON ERROR GOTO 18 
IBELIETES “test 1” 


1@JON ERROR 


CFOR T=8 TO 2 
UREAD LINE$ 


UPUT #PATH,LINE$ 
NEXT -F 
UCLOSE #PATH 


UrFOR 19° TO 8 STEP 


NGET #PATH,LINE 
PROS LTE 
LINEAT T 

UICLOSE #PATH 
JEND 


UDATA "This is test 
UDATA "This is test 
UDATA "This is test 
UDATA "This is test 
UDATA "This is test 
UDATA "This is test 
UDATA "This is test 
UDATA "This is test 
UDATA "This is test 


IDATA "This is test 
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DIM LINE+STRINGI 25) 


USEEK #PATH,LENGTH#T 


UIOPEN #PATH,"test1":READ 


a 


SEEK #PATH;,LENGTH#T 


line 
line 
line 
line 
line 
line 
line 
line 
line 
line 


UCREATE #PATH,"test1":WRITE 


a1" 
#2" 
#3" 
#4" 
45" 
#6" 
#7" 
#8" 
#9" 
#19" 
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SGN Returns a value’s sign 


Syntax: SGN(number) 


Function: Determines whether a number’s sign is positive or 
negative. 


If number is less than 0, then SGN returns -1. If number 
equals 0, then SGN returns 0. If number if greater than 0, 
then SGN returns 1. 


Parameters: 
number The value for which you want to determine the 
sign. 
Examples: 


PRINT SGNC-22) 
PRINT SGNCA) 
PRINT SGNC44-A) 


Sample Program: 


This procedure uses SGN to create half sine waves down the 
screen. SGN tests when the SIN calculation results are positive. 
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PROCEDURE halfsine 

LIDIM FORMULA,CALCULATE,POSITION:REAL 
SHELL. “DISPLAY €c"* 
UFORMULA=CPI+2)/15 
UCALCULATE=FOQRMULA 

USHELL “TMODE -PAUSE™ 

(FOR T=8 TO 100 
LICALCULATE=CALCULATE+FORMULA 
UIPOSITION=INTCSINCCALCULATE)#*10+16) 


HIF SGNCSINCCALCULATE))>@ THEN 
UPRINT TABCPOSITION); '#" 
UENDIF 

| ee ae 8 

USHELL “"TMODE PAUSE" 

UEND 


SS SSS SSS SS 
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SHE LG Forks another shell 


Syntax: SHELL [“string’’][+“string”...][ + variable] 
[+ variable...] 


Function: Executes OS-9 commands or programs from within 
a BASICO9 procedure. Using SHELL, you can access OS-9 
functions, including multiprogramming, utilities, commands, 
terminal and input/output control, and so on. 


When you use the SHELL command, OS-9 creates a new pro- 
cess to handle the commands you provide. If you specify an 
operation, BASICO9 evaluates the expression and passes it to 
the shell for execution. If you do not specify an operation, 
BASICO9 temporarily halts, and the shell process displays 
prompts and accepts commands in the normal manner. In this 


case, press to return to BASICO9. 


When the shell process terminates, BASICO9 becomes active 
and resumes execution at the statement following the SHELL 
statement. 


Parameters: 
string Any OS-9 command or function. String con- 
stants must be enclosed in quotation marks. 
Concatenate string constants and string vari- 
ables using a plus symbol (+). 
variable Any string variable containing an OS-9 com- 


mand or function. 
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Examples: 
SHELL "COPY FILE1 FILE2" 


Shebk “COPY FILE? PiLees* 
SHELL "COPY “*rTLess™ “+ DT RNAMET 7" FILES 
Sten “LIST DOCUMENT" 


Shek "KILL “tS TRS CN? 


Sample Program: 


You must use this procedure with the GET sample program. 
Using the two programs together enables you to copy all the files 
from one directory to another directory. The GET sample pro- 
gram reads the files in a directory and stores them in a file 
named Dirfile. This procedure reads the filenames from Dirfile 
and uses SHELL to copy them to the directory you specify. 


PROCEDURE copyutil 

UDIM PATH,T,COUNT: INTEGER; FILE,JOB,DIRNAME:STRING 
HOPEN #PATH,"dirfile™:READ 

UINPUT "Name of new directory... ",DIRNAME 
USHELL "MAKDIR "+DIRNAME 

PSHELL. “LOAD COPY” 

OWHILE NOTCEOFC#PATH)) DO 

UREAD #PATH,FILE 

OJOB=FILE+" "+DIRNAME+"/"+FILE 

HON ERROR GOTO 1@ 

UPRINT “COPY "s JOB 

USHELL “CORY “+J0B 

180J0N ERROR 

HENDWHILE 

CLOSE #PATH 

WEND 
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SIN Returns the sine of a number 


Syntax: SIN(number) 


Function: Calculates the trigonometric sine of number. You 
can use the DEG or RAD commands to cause number to rep- 
resent a value in either degrees or radians. Unless you specify 
DEG, the default is radians. SIN returns a real number. 


Parameters: 
number The angle of two sides of a triangle for which 
you want to find the ratio. 
Examples: 


PRINT SINC45) 


Sample Program: 


This procedure calculates sine, cosine, and tangent values 
for a number you type. 


PROCEDURE ratiocalc 

LIDEG 

UDIM ANGLE:REAL 

UINPUT “Enter the angle of two sides of «a 


triangle.««", ANGLE 

UPRINT 

DPRINT “Angle "STNE*, “COSTNE*;"* TAN” 

(ak 0 a a a ca a 


UPRINT ANGLE ,SINCANGLE) ,COSCANGLE),TANCANGLE ) 
UPRINT 
END 
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SIZE Returns the size of a data structure 


Syntax: SIZE(variable) 


Function: Returns the size in bytes of a variable, array, or 
data structure. SIZE is especially useful with random access 
files to determine the size of records to store in a file. You can 
also use SIZE to determine the size of variable storage for 
other purposes. 


SIZE returns the size of assigned storage, not necessarily the 
size of a string. For example, if you dimension a variable for 
15 characters, and assign a 10-character string to it, SIZE 
returns 15, not 10. SIZE returns the total size of arrays. That 
is, it returns the number of elements multiplied by the size of 
the elements. 


Parameters: 
variable The variable, array, or data structure for 
which you want to find the size. 
Examples: 


RECORDLENGTH = SIZECA$) 


PRINT “YOUR NAME IS STORED IN As SIZECNAMES); 
~ CHARACTER STRING.” 


Sample Program: 


This procedure creates a simple inventory, stored in a 
file named Inventory. It uses SIZE to calculate the size 
of each element to be stored in the file, and to move 
the pointer to the beginning of each record’s storage 
space. 
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PROCEDURE inventory 

OTYPE INV__ITEM=NAME:STRING(C25]; LIST,COST:REAL; 
QTY: INTEGER 

ODIM INV__ARRAYC10@):INV_ITEM 

ODIM WORK__REC: INV_ITEM 
ODIM PATH: BYTE 

DON ERROR GOTO 18 
ODELETE “inventory” 

1900N ERROR 

OCREATE #PATH,™inventory”" 
OWORK__REC.NAME="""" 
OWORK__REC.LIST=9@ 
OWORKW__REC.COST=@ 
DWORK__REC.QTY=9 
OFOR N=1 TO 199 
OPUT #PATH,WORK__REC 
ONEXT N 

ULOOP 

OINPUT “Record number? ",recnum 
OIF recnum<1 OR recnum>109@ THEN 
OPRINT 

OPRINT “End of Session" 

OPRINT 

OCLOSE #PATH 

LEND 

DENDIF 

OINPUT "Item name? '",WORK__-REC.NAME 
CINPUT “List pricey ,WORK_REC. LIST 
OINPUT “Cost price? ™",WORK_REC.COST 
OINPUT “Quantity? ™,WORK_REC.QTY 
OSEEK #PATH,Crecnum-1)*SIZECWORK_REC ) 
OPUT #PATH,WORK__REC 

HENDLOOP 


END 


| pec SSE SS RE AY EE EE EEE EE A ES EE EE TEE TEE EE 
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SQ Returns the value of a number raised to the 
power of 2 


Syntax: SQ(number) 


Function: Calculates the value of a number raised to the 
power of 2. 


Parameters: 


number The number you want raised to the power of 2. 


Examples: 
PRINT SQC188) 


PRINT PI#SQCR) 


Sample Program: 


This procedure uses SQ in a formula that positions asterisks on 
the screen in a sine wave pattern. 


PROCEDURE sinedown 

UDIM FORMULA,CALCULATE,POSITION:REAL 
USHELL “DISPLAY @Cc™ 
LIFORMULA=CPI+2)/15 
NCALCULATE=FORMULA 

USHELL. “TMODE -PAUSE™ 

FOR T=8 TO 208 
ICALCULATE=CALCULATE+SQCFORMULA) 
UPOSITION=INTCSINCCALCULATE)*12+16) 
UPRINT TABCPOSTT LONI s. te 

NEAT 

USHELL “TMODE PAUSE” 

DEND 
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SQR/ SQRT Returns the square root of a 


number 


Syntax: SQR(number) 
SQRT(number) 


Function: Calculates the square root of a number. SQR and 
SQRT serve the same function. 


Parameters: 
number The number for which you want the square 
root. 
Examples: 


PRINT SQRC188) 


PRINT PI*SQRTCR) 


Sample Program: 


This procedure uses SQRT in a formula to position asterisks on 
the screen in a sine wave pattern. 


PROCEDURE saqrdown 
ODIM FORMULA,CALCULATE,POSITION:REAL 
OSHELL “DISPLAY @C" 

OFORMULA=PI/15 

OCALCULATE=FORMULA 

LSHELL. “TMODE =PAUSE™ 

OFOR T=8 TO 200 
OCALCULATE=CALCULATE+SQRT CFORMULA) 
OPOSITION=INTCSINCCALCULATE)#12+16) 


OPRINT TABCPOSITION); “*" 
UNEXT T 
USHELL ““TMODE PAUSE” 


LEND 


DN a aaaaaacaaaaaaacaaaaaaaacacacaaasaaaaaaacaaaaaaaaa 
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STEP Establishes the size of increments in a 
FOR loop 


Syntax: 


FOR variable = init val TO end val [STEP value] 


[procedure statements] 


NEXT variable 


Function: STEP provides an increment value in a FOR/NEXT 
loop. If you do not specify a STEP value, the loop steps in 


increments of 1. 


BASICO9 executes the lines following the FOR statement until 
it encounters a NEXT statement. Then it either increases or 
decreases the initial value by 1 (the default) or by the value 
given by STEP. If you give the loop an initial value that is 
greater than the final value, and specify a negative value for 
STEP, the loop decreases from the initial value to the end 


value. 


Parameters: 
variable 
init val 
end val 
value 


procedure 
statements 


Any legal numeric variable name. 
Any numeric constant or variable. 
Any numeric constant or variable. 


Any numeric constant or variable. 


Procedure lines you want to be executed 


within the loop. 
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Examples: 


FOR COUNTER = 1 to 108 STEP .5 
PRINT COUNTER 
NEXT COUNTER 


EDR: 4 480° TO 1 STer- 4 
PRINT -x 
NEXT -X 


FOR TEST -* A TO-BO-SIEP KATE 
PRINT “leat 
NEXT TEST 


Sample Program: 


This procedure reverses the order of characters in a word or 
phrase you type. It uses STEP to decrement a counter that 
points to each character in the string in reverse order. 


PROCEDURE reverse 

ODIM PHRASE:STRING; T,BEGIN: INTEGER 
OPRINT "Type a word or phrase you want to 
reverse:"'; 

PRINT 

OINPUT PHRASE 

OBEGIN=LENCPHRASE ) 
OPRINT "This is how your phrase looks backwards:" 
OFOR T=BEGIN TO 1 STEP -1 

OPRINT MID$CPHRASE,T,1);3 

ONEXT T 

UPRINT 


LEND 
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STOP Terminates a procedure 


Syntax: STOP [“string’’] 


Function: Causes a procedure to cease execution, print the 
message “STOP Encountered’, and return control to 
BASICO9’s command mode. You can also specify additional 
text to display when BASICO9 encounters STOP. 


Use stop when you want a procedure to terminate without 
entering the DEBUG mode. 


Parameters: 

string Text to display when STOP executes. 
Examples: 

STOP “Program terminated before comoléetion.” 

IF RESPONSE = "VY" THEN STOP “Program terminated 


at your request." 
ENDIF 
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STR$ Converts numeric data to string data 


Syntax: STR$(number) 


Function: Converts a numeric type to a string type. This lets 
you display the number as a string or use string operators on 
a number. The conversion replaces the numeric values with 
the ASCII characters of the number. STR$ is the inverse of 
the VAL function. 


Parameters: 


number Any numeric-type data. 


Examples: 
PRINT STR$(1019) 


DIM I:INTEGER 
1=44 
PRINT STR$CI) 


DIM BtsyTs 
B=001 
PRINT STR$CB) 


DIM R:REAL 
R=1234.56 
PRINT STRS$CR) 


Sample Program: 


This procedure calculates an exponential value, then adds the 
necessary number of zeroes to convert it to standard notation. It 
uses STR$ to convert the number you type to a string type value 
so that it can use string functions to add the zeroes. 
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PROCEDURE bignum 

UDIM C,PLACES,B,SIGN:STRING; EX,COUNT,NEWCOUNT, 
DECIMAL: INTEGER 

UDIM NEW,ZERO,NEWEST:STRING([10@] 

NCOUNT=-1 
UZERO="@OOGGOOBOOOD0O0000000000000000000000" 
UNEW=""*" \NEWEST="" 

UINPUT “What number do you want to raise to the 
power of 147...™, NUM 

LA=NUM*%14 

UB=STR$CA) 

HEX=SUBSTRC"E",B) 


USIGN=MID$CB,EX+1,1) 


LIPLACES=RIGHT$(B,LENCB)-EX-1) 
UFOR T=1 TO LENCB) 
UC=MID$C€B,T,1) 

LiF C=". - THEN 

UDECIMAL=@ 

UGOTO 18 

BEND LF 

UDECIMAL=DECIMAL +1 

DIF C="E" THEN 100 

UNEW=NEW+C 

1OUNEXT T 
1@@UNEWCOUNT=VALCPLACES)-DECIMAL 
UINEW=NEW+LEFT$CZERO,NEWCOUNT+1 9 
FOR T=LENCNEW) TO 1 STEP -1 
UICOUNT=COUNT +1 
UINEWEST=MID$CNEW,T,1)+NEWEST 
UIF MODCCOUNT,3)=2 AND T>1 THEN 
UNEWEST="","+NEWEST 


UENDIF 

UNEAT -F 

PRINT NUM; " to the power of 14 = ": a 
PRINT “= "ss NEWEST 

DEND 
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SUBSTR Searches for specified characters in 
a string 


Syntax: SUBSTR(targetstring,searchstring) 


Function: Searches for the first occurrence of targetstring 
within searchstring and returns the numeric value of its loca- 
tion. SUBSTR counts the first character in searchstring as 
character Number 1. Therefore, if you searched for the string 
“worth” in the string “Fortworth”, SUBSTR returns a value of 
5. 


If SUBSTR cannot find targetstring, it returns a value of 0. 


Parameters: 
targetstring The group of characters you want to locate. 
searchstring The string in which you want to find 
targetstring. 
Examples: 


PRINT SUBSTRC"THREE", "ONETWOTHREEFOURFIVESIX") 


X=SUBSTRE™ “ FULLNAMES? 


Sample Program: 


This procedure selects the last name from a string con- 
taining both a first name and a last name. It uses 
SUBSTR to find the space between the two names in 
order to determine where the last name begins. 
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PROCEDURE lastname 

UDIM NAMES:STRING; LASTNAME:STRING[I10] 
UPRINT "Here are the last names:" 

FOR T=1 TO 1@ 

UREAD NAMES 

UPOINTER=SUBSTRC" '", NAMES) 
UPOINTER=LENCNAMES)-POINTER 
ULASTNAME=RIGHT$CNAMES ,POINTER) 

UIPRINT LASTNAME 

NEST 

UDATA "Joe Blonski","Mike Marvel","Hal 
Skeemish","Fred Laungly"™ 

LIDATA "Jane Misty", "Wendy Paston","Martha 
Upshong","Jacqueline Rivers" 

DATA "Susy Reetmore","Wilson Creding™ 
LIEND 


SR RETIREES ERE PEASE IE STE SD NS ESSE SRE SESE SE, ER ESS ESL SESE SS SENS SS LE SI LEER TSE ST SE i ST SI I ST EE A SEI EI EE ERO 
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SYSCALL Executes an OS-9 System Call 


Syntax: SYSCALL callcode registers 


Function: Lets you execute any OS-9 system call from 
BASICO9. Use this command to directly manipulate your sys- 
tem or data or to directly access devices. 


Be careful! Used improperly, SYSCALL can cause undesira- 
ble results—you might unintentionally format a disk or 
destroy disk or memory data. Before using SYSCALL, you 
should be familiar with assembly language programming and 
should understand the system call information in the OS-9 
Technical Reference manual. The OS-9 Technical Reference 
manual provides information about all OS-9 system calls. 


To pass required register values to the SYSCALL command, 
create a complex data structure that contains values for all 
registers. For example: 


TYPE REGISTERS=CC,A,B,DP:BYTE; X,Y,U: INTEGER 
DIM REGS: REGISTERS 
DIM CALLCODE:BYTE 


The complex data type REGISTERS contains values for all 
registers. Unless you specifically assign values to variables 
(for instance, REGS.CC, REGS.A, and REGS.B in the pre- 
vious example), they contain random values. See the TYPE 
command for further information. 


Parameters: 
callcode is the request code of the system call you wish 
to use. All system call codes are referenced in 
the OS-9 Technical Reference manual. 
registers is a list of the register entry values required 


for the system call you are using. 


Examples: see “Sample Programs.” 
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Sample Programs: 


The following programs set up a data type (REGISTERS) for the 
register variables. Before executing SYSCALL, the procedures 
store the required register entry values in the complex data 
structure REGS. The procedures also establish CALLCODE as a 
variable to hold the request code of the system call you want to 
use. 


The Writecall procedure uses the string variable TEST to store 
text that it writes to the screen through Path 0 (the standard 
output path) using System Call $8A, I$Write. Before the proce- 
dure calls I$Write, it stores the appropriate path number (0) in 
Register A. The ADDR command calculates the address of the 
variable TEST, and the LEN command determines the length of 
the variable. The procedure stores these two values in Registers 
X and Y. 


The Readcall uses System Call $8B, I$ReadLn to perform a 
function that is the opposite of Writecall. Readcall establishes 
TEST as a string variable into which it writes the characters 
you type. Because the length of TEST is restricted to ten charac- 
ters (DIM TEST:STRING[161), the terminal bell sounds if you 
attempt to type more than 10 characters. Pressing [ENTER] 
terminates the call and the procedure prints the contents of 
TEST—the characters you typed. 
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PROCEDURE WriteCall 

OTYPE REGISTERS=CC,A,B,DP:BYTE; X,Y,U: INTEGER 
(DIM REGS:REGISTERS 

ODIM PATH,CALLCODE: BYTE 

ODIM TEST:STRING(586] 

OTEST="This is a test of I$Write, System call 
S$SA.44" 

OREGS.A=9 

OREGS.X=ADDRCTEST ) 

DOREGS.Y=LENCTEST) 

OCALLCODE=$8A 

ORUN SYSCALLCCALLCODE ,REGS) 

LIPRINT 

HEND 


PROCEDURE Readcall 

OTYPE REGISTERS=CC,A,B,DP:BYTE; X,Y,U: INTEGER 
ODIM REGS:REGISTERS 

DDIM PATH,CALLCODE:BYTE 
ODIM TEST:STRING(183 
DREGS.A=8 
DREGS.X=ADDRCTEST) 
DREGS.¥=18 

OUCALLCODE=$8B 

DRUN SYSCALLCCALLCODE ,REGS) 
LIPRIN ET 

EPRINT TEST 

UEND 
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TAB Causes PRINT to jump to the specified 
column 


Syntax: TAB(number) 


Function: Causes PRINT to display the next PRINT item to 
display in the column specified by number. If the cursor is 
already past the desired tab position, BASICO9 ignores TAB. 


Use POS to determine the current cursor position when dis- 
playing characters on the screen. 


Screen display columns are numbered from 1, the leftmost col- 
umn, to a maximum of 255. The size of BASICO9 output 
buffer varies according to the stack size. 


You can also use TAB with PRINT USING statements. 


Parameters: 
number The column at which you want PRINT to 
begin. 
Examples: 


PRINT TABC28);TITLES$ 
PRINT TABCX);ITEMNUMBER; ITEM$ 


Sample Program: 


This procedure uses asterisks to simulate a sine wave on the 
screen. It uses TAB to position each asterisk in the proper 
location. 
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PROCEDURE sinewave 
UDIM FORMULA,CALCULATE,POSITION:REAL 
USHELL "DISPLAY gC" 


= 


UFORMULA=CPI+2)/15 
LICALCULATE=FORMULA 


SRE." GODE.-- PAUSE 
LFOR T=8 TO 209 


UCALCULATE=CALCULATE+SQCFORMULA) 


— 


UPOSITION#INTCSINCCALCULATE)+*#12+16) 


DPRINT TABCPOS!I TIONS 5: ee 
NEXT. 7 
DSREil. "(MODE PAUSE” 


JEND 
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TAN Returns the tangent of a value 


Syntax: TAN(number) 


Function: Calculates the trigonometric tangent of number. 
Using DEG or RAD, you can specify the measure of the angle 
(number) in either degrees or radians. Radians are the default 
units. 


Parameters: 
number The angle for which you want to find the 
tangent. 
Examples: 


PRINT TANC45) 


Sample Program: 


This procedure calculates sine, cosine, and tangent values for a 
number you type. 


PROCEDURE ratiocalc 

LIDEG 

UDIM ANGLE:REAL 

UINPUT "Enter the angle of two sides of a 


Peng bes «a sANGLE 

LIPRINT 

UPRINT “angie. "SINE"."CUSINE’ "TAN 

UPRINT "“------------------------------------------ 


UPRINT ANGLE,SINCANGLE),COSCANGLE),TANCANGLE) 
PRINT 
UEND 
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TRIMS$ Removes spaces from the end of a string 


Syntax: TRIMS§(string) 


Function: Removes any trailing spaces from the end of the 
specified string. This function is particularly useful for trim- 
ming records you recover from a random access file. 


Parameters: 
string The string or string variable from which you 
wish to remove trailing spaces. 
Examples: 


PRINT TRIM$CA$) 


GET A$,BS,C$ 
PRINT TRIM$CA$),TRIM$CBS),TRIMSCCS$) 


Sample Program: 


This program takes names you type and puts them in a 
random access disk file. Because random access files use 
the same amount of storage for each item, short names 
are padded with extra spaces. When reading the names 
back from the file, the procedure uses TRIM$ to remove 
these extra spaces. 


PROCEDURE namestor 

ODIM NAMES,TEMP1,NAMEC108):STRING[26]; FIRST,LAST: 
STRING[L15]; INITIAL: STRING[1] 
ODIM PATH,T: INTEGER 

UNAMES="""" 

HOON ERROR GOTO 19 

ODELETE “namelist" 

18J0N ERROR 

OCREATE #PATH,"namelist":UPDATE 
UFOR T=1 TO 108 

UINAMECT)="""" 

UNEXT. T 

T=@ 


Ee eA SS TE SE SE SE A I TO ELBE DI LI ICES LEE ELLIE IE ELIE LT 
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LILOOP 

LLENPUT “Fire? Namet-*,F RST 
WEXITLE FIRSTS" THEN 
OCLOSE #PATH 

GOTO 108 

HENDEXIT 


PEN POT MO fai PNET LAL 

INPUT “Last: “LAST 

LT=T +1 

UINAMECTI=FIRST+" "+INITIAL+" "+L AST 
(IPUT #PATH,NAMECT) 

USEEK #PATH,T*26 

UENDLOOP 

1@@JOPEN #PATH,"namelist"™:READ 

GP RINT %S PRINT 

UPRINT “Lastname","Firstname","Initial"™ 

REM Print underline (40 characters) 

Le ae Ai ida nee cae eC ee aE se ee a 
PRINT 

USEEK #PATH,@ 

UT=9 

WHILE NOTCEOFC#PATH)) DO 
UIGET #PATH,NAMES 
UT=T+1 
LINAMES=TRIMS$CNAMES) 

UX=SUBSTRC"™ ", NAMES) 
LIFIRST=LEFTS$CNAMES,X-1) 
UTEMP1=RIGHT$CNAMES,LENCNAMES)-X+1) 
UINITIAL=MID$CTEMP1 ,2,1) 
WLASTHRIGHTSCTEMP1T ~LENCTEMP1)=3) 
PRINT LAST, FE RST, INIT DAL 

SEEK #PATH,T*26 

HENDWHILE 

CLOSE #PATH 


END 
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TRON / TROFF Turns on/off trace function 


Syntax: TRON 
TROFF 


Function: Turns on or off the BASICO9 trace mode. When 
trace is turned on (TRON), BASICO9 decompiles and displays 
each statement in a procedure before execution. BASICO9 also 
displays the result of each expression after evaluation. This 
function lets you follow program flow and is helpful in debug- 
ging and analyzing the execution of a procedure. After the 
procedure is debugged, remove the TRON statement. 


If you want to view only a portion of a procedure’s execution, 
surround that portion with TRON and TROFF. Tracing 
begins immediately after the TRON statement and ends at 
the TROFF statement. The rest of the program executes 
normally. 


Parameters: None 


Examples: 


BS$="GOOBOOOOBOOBOHO00000"+BS 
N=1+LENCB$) 

FOR be4 TO -) STEP <1 

TRON 

N=N-4 

ACI V=VALCMID$CB$ ,N,4)) 

TROUPE 

NEXT I 
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TRUE Returns a Boolean TRUE value 


Syntax: variable=TRUE 


Function: TRUE is a Boolean function that always returns 
True. You can use TRUE and FALSE to assign values to Boo- 
lean variables. 


Parameters: 
variable The Boolean storage unit you want to set to 
True. 
Examples: 


DIM TEST:BOOLEAN 
TEST=TRUE 


Sample Program: 


This procedure asks five questions. If your answer is correct, it 
stores the Boolean value TRUE in a Boolean type variable. If 
your answer is incorrect, it stores the Boolean value FALSE in 
the variable. 


PROCEDURE quiz 

UDIM REPLY,VALUE:BOOLEAN; ANSWER:STRING[1]; 
QUESTION: STRING[8@] 

OUFOR T=1 TO 5 

UREAD QUESTION,VALUE 

UIPRINT QUESTION 

UPRINT "CT) = TRUEQOUDOODOCF) = FALSE" 

PRINT “Select. T of Fei: 

GET #1,ANSWER 

HIF ANSWER="T' THEN 

DREPLY=TRUE 

WELSE 

UREPLY=FALSE 

WENDT 

HIF REPLY=VALUE THEN 

UPRINT \ PRINT "That’s Correct...Good Show!" 
eae 
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DPRINT "Sorry, you*re wrong...Better Luck next 
time." 

DENDIF 

OPRINT \ PRINT \N PRINT 

LINEXT T 

DATA "In computer talk, CPU stands for Central 
Packaging Unit.", FALSE 

ODATA "The actual value of 64K is 65536 
bytes.”, TRUE 

ODATA “The bits in a byte are normally numbered Q 
thredon 7a", TRUE 

ODATA "BASIC@9 has four data types.™,FALSE 
UDATA "The LAND function is a Boolean type 
operator.” ,FALSE 

LEND 
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TYPE Defines a data type 


Syntax: TYPE name = typedeclar [;typedeclar{,...]] 


Function: Defines new data types (complex data structures). 
New data types are vectors (one-dimensional arrays) of previ- 
ously defined types. Structures created by TYPE differ from 
arrays in that they can consist of elements of different types, 
and BASICO9 accesses elements by field names rather than by 
an indexed position. 


Parameters: 
name The name you select for the new data type. 
typedeclar One or more type declarations, which can con- 
sist of field names, type declarations, and sub- 
scripts. Separate different types or different 
lengths of string declarations with semicolons. 
Notes: 


@ Complex data structures allow you to create data types that 
are appropriate for a specific task. You can organize, read, 
and write associated data naturally. Also, BASICO9 estab- 
lishes and defines element positions at compilation time. 
This saves time and overhead at run time because 
BASICO9 can access the elements of a data structure faster 
than it can access the elements of an array. 


@ When you define new data structures using TYPE, you can 
include any of the five existing data types (string, real, 
integer, byte, and Boolean), or you can include data struc- 
ture types that you previously defined with TYPE. This 
means that your structures can be simple or very complex, 
such as non-rectangular data lists or trees. 


@ TYPE does not create storage. You create storage using the 
DIM statement, after using TYPE. 


@ To access elements of a data structure, use the field name 
as well as any appropriate element index. 
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@ For more information on creating and using complex data 
types, see “Complex Data Types” in Chapter 6. 


Examples: 


TYPE LIBRARY=TITLE, AUTHOR, PUBLISHER: STRING AS ]3 
REFERENCES INTEGER 
DIM BOOKC500):LIBRARY 


TYPE PARTS#=ITEM,LOCATION:STRING(L2913 CAT:REAL; 
QUANTITY;INTEGER 
DIM INVENTORYC1080):PARTS 


Sample Program: 


This procedure builds an array to contain a book reference list, 
including the book title, the author’s name, the publisher, and a 
reference number. It does so by using TYPE to create a special 
data structure to store all the information for each book. 


PROCEDURE books 

LIT¥YPE LIBRARY=TITLE, AUTHOR, PUBLISHERsSTRINGI S@] ; 
REFERENCE: INTEGER 

UDIM BOOKS(198):LIBRARY 

LIT = @ 


ULOOP 
OT =T+1 

DINPUT “BOOK TITLE. ss", BT$ 
DUBOOKSCT).TITLE=BT$ 

HEXITIF BOOKSCT).TITLE="" THEN 
UGOTO 100 

DENDEXIT 

OINPUT “Book Author...",BA$ 
UBOOKSCT).AUTHOR=BA$ 

INPUT “Book: Publisner.«a "s+ BPs 
DBOOKSCT).PUBLISHER=BP$ 

OINPUT “Reference Number...'',BOOKSCT).REFERENCE 
HJENDLOOP 

1@@0FOR X=1 TO T-1 


DPRINT, BOOKSC x22 TLTLES ? 4-09 BOURSCAD nus. & 


UBDOKSCX).PUBLISHERS * » s BOOKSCA). REFERENCE 
UNEXT xX 
END 
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UN TIL Terminates a REPEAT loop on specified 
condition 


Syntax: REPEAT 
procedure lines 
UNTIL expression 


Function: Ends a REPEAT loop. REPEAT establishes a loop 
that executes the encompassed procedure lines until the 
result of the expression following UNTIL is true. Because the 
loop is tested at the bottom, the lines within the loop are exe- 
cuted at least once. 


Parameters: 
procedures Statements you want to execute in the loop. 
lines 
expression A Boolean expression (the result must be 
either True or False). 
Examples: 
REPEAT 


COUNT = COUNT+1 
UNTIL COUNT > 108 


ENPUT: Xo ¥ 

REPEAT 

| ae ll 

pe Sad 

UNTIL. X41 OR Y<O 


See REPEAT for more information. 
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USING Formats PRINT output 


Syntax: PRINT [#path] USING [format,] data|;data...] 


Function: Prints data using a format you specify. This state- 
ment is especially useful for printing report headings, 
accounting reports, checks, or any document requiring a spe- 


cific format. 


USING is actually an extension of the PRINT statement. The 
same rules that apply to the PRINT statement also apply to 
the PRINT USING statement (see PRINT). 


Parameters: 


path 


format 


data 


The number to an opened device or file. If you 
do not specify path the default is #1, the video 
screen (standard output device). To print to 
another device or file, first OPEN a path to 
that file or device (see OPEN). 


An expression specifying the arrangement of 
the displayed data. 


Any numeric or string constant or variable. 
Always enclose string constants within quota- 
tion marks. Separate all data items with 
semicolons or commas. 


See PRINT USING for more information. 
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VAL Converts string data to numeric data 


Syntax: VAL(string) 


Function: Converts string-type data to numeric-type. VAL is 
the inverse of the STR$ function. It returns the real value 
represented by the characters in a string. If any character in 
the specified string is not numeric, BASICO9 returns an error. 


Parameters: 
string An ASCII string containing one or more of the 
following characters: 0123456789. + $-. 
Examples: 


PRINT VALC123) 


AS="44.66" 
PRINT VALCA$) 


Sample Program: 


This procedure calculates an exponential value, then adds the 
necessary number of zeroes to convert it to standard notation. It 
uses STR$ to convert the original number to a string, then uses 
VAL to convert the exponent into a value to determine the cor- 
rect decimal place. 


PROCEDURE bignum 
ODIM C,PLACES,B,SIGN:STRING; EX, COUNT.;NEWCOUNT, 


DECIMAL# INTEGER 


UDIM NEW,ZERO,NEWEST:STRING[190@] 

LICOUNT=-1 
NZERO="GQOOOROBB0000000000000000000000000000" 
UINEW="""= \NEWEST="" 

HINPUT “What number do you want to raise to the 
Owe OF 14% .24"* NUM 

LIA=NUM%1 4 

UB=STR$CA) 


JEA*® SUBST RO EB? 
UISIGN=MID$CB,EX+1,1) 
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DPLACES=RIGHT$C(B,LENCB)-EX-1) 
CPOR. T=1 TO LENCE) 
OC=MID$C(B,T,1) 
IF C=" THEN 
UDECIMAL=9 


UGOTO 19 
ERD EF 
ODECIMAL=DECIMAL+1 


HIF C="E" THEN 108 
UNEW=NEW+C 

1QUNEXT T 
1@@QONEWCOUNT=VALCPLACES)-DECIMAL 
UNEW=NEW+LEFT$C ZERO ,NEWCOUNT +1) 
FOR “P=LENCNEW?: TH 1 -Sier-=4 
UCOUNT=COUNT +1 
OUNEWEST=MID$CNEW,T,1)9+NEWEST 

DIF MODCCOUNT,3)=2 AND T>1 THEN 


ONEWEST=","*+NEWEST 

DENDIF 

NEXT. TE 

PRINT NUNS * 16: the cower oT T4 
PRINT **="'s- NEWEST 

DEND 
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WHILE/ D O/ E N DWHILE Establishes 


a loop 


Syntax: WHILE expression DO 
procedure lines 
ENDWHILE 


Function: Establishes a loop that executes the encompassed 
procedure lines while the result of the expression following 
WHILE is true. Because the loop is tested at the top, the 
lines within the loop are never executed unless the expression 
is true. 


Parameters: 
expression A Boolean expression (has a result of True or 
False). 
procedure Program lines to execute if the expression is 
lines true. 
Examples: 


WHILE COUNT < 12 DO 
COUNT = COUNT+1 
ENDWHILE 


Sample Program: 


You must create a file of directory names using the GET sample 
program before you can use the following procedure. Copyutil 
uses the filenames created by the GET sample program to copy a 
directory’s files to another directory you specify. You must spec- 
ify a directory name that does not exist. Copyutil uses a 
WHILE/DO/ENDWHILE loop to continue copying until BASIC09 
reaches the end of the file. 
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PROCEDURE copyutil 

ODIM PATH,T,COUNT: INTEGER; FILE,JOB,DIRNAME:STRING 
OOPEN #PATH,"dirfile"™:READ 

OINPUT "Name of new directory. s."«DIRNAME 

OSHELL "MAKDIR "+DIRNAME 

OSHELL "LOAD COPY" 

OWHILE NOTCEOFC#PATH)) DO 

OREAD #PATH,FILE 

NJOB=FILE+™ "+DIRNAME+"/"+F ILE 


= 


CON ERROR GOTO 19 
OPRINT "COPY "; JOB 
OSHELL "COPY "+J0B 
1@00N ERROR 
DENDWHILE 

OCLOSE #PATH 


UEND 
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WRITE Writes data to a sequential file or 
m device 


Syntax: WRITE [#path,] data 


Function: Writes an ASCII record to a sequential file or to a 


device. 
Parameters: 
path A variable containing the path number of the 
file or device to which you want to send data. 
Path can be one of the the standard I/O paths 
(0742 
data The data you want to send over the specified 
path. 
Notes: 
The following information deals with writing sequential disk 
files: 


@ To write file records, you must first dimension a variable to 
contain the path number of the file, then use OPEN or 
CREATE to open a file in the WRITE or UPDATE access 
mode. 


@ Records can be of any length within a file. 


® Individual data items in the input record are separated by 
ASCII null characters. You can also separate numeric items 
with comma or space character delimiters. Each input 
record is terminated by a carriage return character. 


Examples: 
om WRITE #PATH,DATAS$ 


WRITE #1,RESPONSE$ 


WRITE #OUTPUT,INDEXCX) 
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OPEN #PATH,™"namefile™:WRITE 

FOR. b=t To 72 

READ NAMES 

WRITE #PATH, NAMES 

NEXD 

CLOSE #PATH 

DATA: Mats MGR SUE se NA go Ae 

DATA "SAL." MLOKDE 4" FRED’ "MARY 3 ACNATE” 


Sample Program: 


This procedure selects 100 random values between 1 and 10. It 
uses WRITE to place the values into a disk file. Next, it reads 
the values from the file and uses asterisks to indicate how many 
times RND selected each value. 


PROCEDURE randlist 
UDIM SHOW,BUCKET:STRING 
LUDIM T;PATH,SELECTC193,R: INTEGER 


[BUCKET =" e# RRR HHH HHH HEHEHE HEH HHH HN 
FOR T=1 TO 10 

USELECTCT)=@ 

UNEXT T 

LION ERROR GOTO 198 

SHELL. “DEL. RANDEILLE™ 

18) ON ERROR 

LICREATE #PATH,“randfile™: UPDATE 
LUFOR T=1 TO 109 

UR=RNDC9) +1 

OWRITE #PATH,R 

LINEXT T 

DOPRINT "Random Distribution" 
OSEEK #PATH,@ 

UFOR T=1 TO 109 

READ #PATH,NUM 

HUSELECTCNUM)=SELECTCNUM) +1 

UNEXT T 

LIFOR T=1 TO 10 

USHOW=RIGHT$CBUCKET ,SELECTCT)) 

UPRINT USING “S6<.13¢,52¢,S20<".,"Namber™, 7 4°" 
SHOW 

UNEXT TT: 

UCLOSE #PATH 

LEND 
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XOR Returns the exclusive OR of two values 


Syntax: operand! XOR operand2 


Function: Performs the logical exclusive OR operation on two 
or more values, returning a value of either TRUE or FALSE. 


Parameters: 
operand! Boolean values or expressions (that result in 
operand2 values of True or False). 

Examples: 


PRINT A>2 XOR Bd3 


PRINT AS="YES"™ XOR BS="YES” 


Sample Program: 


This procedure lets two people type numbers until one of them 
guesses the number that the computer picks. It uses XOR to 
determine that one of the numbers typed is the correct number, 
but not both. 


PROCEDURE drawstraw 

UDIM NUM1,NUM2,R:INTEGER; A:BOOLEAN 
PRINT “This program will help you pick" 

PRINT “between two people. Choose who will be” 
UPRINT "Person 1 and who will be Person 2." 
NIPRINT "Then, enter numbers between 1 and 16" 
PRINT “when requested." 

UPRINT 

UR=RNDC10) 

1Q8UINPUT "Person 1, type a number and press 
ENTER & 2 NUM 

UINPUT "Person 2, type a number and press 
ENTER««.™",NUM2 

UA=NUM1=R XOR NUM2=R 

LIF A=FALSE THEN 

UPRINT “"Youtll have to try again..." 

LIPRINT 
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UGOTO 190 

DENDIF 

OIF NUM1=R THEN 

OPRINT "You win, Person 1" 
DENDIF 

OIF NUM2=R THEN 

DOPRINT "You win, Person 2" 
DENDIF 

OPRINT "The Number was...""3 R 
OEND 


eee ee re eee ee eee eee ——EE==_=_—_=== 
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Program Optimization 


BASIC09’s multipass compiler produces a compressed and optim- 
ized low-level I-code for execution. Compared to other BASIC lan- 
guages, BASICO9 greatly decreases both the storage space 
required for program code and the execution speed of programs. 


Because BASICO9 produces I-code at a powerful level, it can 
handle numerous MPU (micro processor unit) instructions with a 
single interpretation. Therefore, for complex programs, there is 
little performance difference between the execution of I-code and 
pure machine-language instructions. 


Most BASIC languages have to compile from text as they run, or 
search tables of tokens in order to execute code. Instead, 
BASICO9 I-code instructions contain direct references to vari- 
ables, statements, and labels. BASICO9 fully utilizes the power of 
the 6809 instruction set, as well, which is optimized for efficient 
execution of compiler-produced code. 


Because BASICO9 interprets I-code, you have a variety of entry- 
time and run-time tests and development aids. The editor reports 
syntax errors immediately when they are entered. The debugger 
lets you debug using original program source statements and 
names. The I-code interpreter performs run-time error checking 
of array structures and BASICO9 functions. 


Optimum Use of Numeric Data Types 


The following notes apply to the use of BASICO9 numeric data 
types: 


@ BASICO09 includes several different numeric representa- 
tions (real, integer, byte), and performs automatic type 
conversions between them. This means that without 
care, your code might contain expressions or loops that 
take more than ten times longer to execute than is 


necessary. 
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@ Some BASICO9 numeric operators, such as +,-,*, and /, 


and some BASIC09 control structures include versions for 
both real and integer values. Integer versions execute 
much faster and can have slightly different properties. 
For instance, integer division discards any remainder. 


Integer operations are faster because they use corre- 
sponding 6809 instructions. Using integers increases 
speed and decreases storage requirements. Integer opera- 
tions use the same symbols as real operations, but 
BASICO09 automatically selects the integer operations 
when when all operands of an expression are of byte or 
integer type. 


Type conversion takes time. Using expressions with oper- 
ands and operators of the same kind is most efficient. 


BASICO09’s real (floating point) math provides excellent 
performance. It includes a 40-bit binary floating point 
representation and uses the CORDIC technique to derive 
all transcendental functions. This integer shift-and-add 
technique is faster and more consistent than the common 
series-expansion approximations. 


At times, you can obtain similar or identical results in a 
number of different ways and at different execution 
speeds. For example, if the variable Value is an integer, 
then Value*2 is a fast integer operation. However, if the 
expression is Value+2.9, 2.0 is represented as a real 
number and the operation requires real multiplication. 
BASICO9 must transform the integer Value into a real 
value. If the result of the expression is assigned to an 
integer type variable, BASICO9 must transform the 
result back to an integer type. The decimal point can 
slow the operation by about ten times. 
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Arithmetic Functions Ranked by Speed 
Typical Speed 


Operation in MPU Cycles 
Integer add or subtract 150 
Integer multiply 240 
Real add 440 
Real subtract 540 
Integer divide 960 
Real multiply 990 
Real divide 3870 
Real square root 7360 
Real logarithm or exponential 20400 
Real sine or cosine 32500 
Real power 39200 


Referring to the previous table can help you in your program- 
ming. For instance, notice that it is quicker to add a value to 
itself rather than multiplying it by 2. Similarly, multiplying a 
value by itself or using SQ on a value is much faster than rais- 
ing a value to the power of 2. 


Notice that a real divide takes 3870 cycles, while a real multipli- 
cation takes only 990 cycles. Multiplying a value by 0.5 is four 
times quicker than dividing the value by 2. 


Quicker Loops 


BASICO9 has two versions of FOR/NEXT loops, one for integer 
loop counter variables and one for real loop counter variables. It 
automatically uses the appropriate version. Integer FOR/NEXT 
loops are much faster than real FOR/NEXT loops. 


Other kinds of loops also run faster if you use integer type vari- 
ables for the loop counters. When writing program loops, remem- 
ber that statements inside the loop can execute many times for 
each execution outside the loop. Whenever possible, compute val- 
ues before entering loops. 
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Arrays and Data Structures 


The internal workings of BASICO9 use integer numbers to index 
arrays and complex data structures. This means that BASICO9 
must convert real type variable or expression subscripts before it 
can handle them. Using integer expressions for subscripts 
increases execution speed. 


Using the assignment statement LET to copy identically sized 
data structures is much faster than copying arrays or structures 
element-by-element inside a loop. 


The PACK Command 


PACK causes a second compilation of a specified procedure. 
Depending on such variables as the number of procedure com- 
ments and the inclusion of line numbers, packed procedures exe- 
cute from 10 to 30 percent faster. Line numbers cause unpacked 
procedures to run slower. 


Minimizing Constant Expressions 
and Subexpressions 


For maximum execution speed, precalculate constant expres- 
sions. For instance, x = x+5 produces the same result as x = 
x+sqrt(€18@)/2. However, the first expression requires approxi- 
mately 150 MPU cycles while the second expression requires 
11,650 MPU cycles. If you use such an expression inside a loop, 
the additional execution time is enormous. 


Input and Output 


Accessing data one line or record at a time is much faster than 
accessing it one character at a time. Also, the GET and PUT 
statements are much faster than READ and WRITE statements 
when accessing disk files. This is because GET and PUT use the 
same binary format as BASICO09’s internal operations. READ, 
WRITE, PRINT, and INPUT must perform binary-to-ASCII or 
ASCII-to-binary conversions, which take more time. 
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Error Codes 


Signal Errors 


Code 


1 
2 
3 


Meaning 


Unconditional termination 
Keyboard termination 
Keyboard interrupt 


BASICO09 Error Codes 


Code 


10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 


Meaning 


Unrecognized symbol 

Excessive verbiage 

Illegal statement construction 

I-code overflow, need more workspace memory 
Illegal channel reference, bad path number given 
Illegal mode (read/write/update) - directory only 
Illegal number 

Illegal prefix 

Illegal operand 

Illegal operator 

Illegal record field name 

Illegal dimension 

Illegal literal 

Illegal relational 

Illegal type suffix 

Too-large dimension 

Too-large line number 

Missing assignment statement 

Missing path number 

Missing comma 

Missing dimension 

Missing DO statement 

Memory full, need more workspace memory 
Missing GOTO 

Missing left parenthesis 

Missing line reference 

Missing operand 

Missing right parenthesis 

Missing THEN statement 

Missing TO 
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Code 


40 
41 
42 
43 
ad 
45 
46 
47 
48 
49 
00 
ol 
a2 
53 
54 
at 
56 
a7 
58 
59 
60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
75 
76 
U7 
78 
79 
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Meaning 


Missing variable reference 
No ending quote 

Too many subscripts 
Unknown procedure 
Multiply-defined procedure 
Divide by zero 

Operand type mismatch 
String stack overflow 
Unimplemented routine 
Undefined variable 

Floating overflow 

Line with compiler error 
Value out of range for destination 
Subroutine stack overflow 
Subroutine stack underflow 
Subscript out of range 
Parameter error 

System stack overflow 

I/O type mismatch 

I/O numeric input format bad 
I/O conversion: number out of range 
Illegal input format 

I/O format repeat error 

I/O format syntax error 
Illegal path number 

Wrong number of subscripts 
Non-record-type operand 
Illegal argument 

Illegal control structure 
Unmatched control structure 
Illegal FOR variable 

Illegal expression type 
Illegal declarative statement 
Array size overflow 
Undefined line number 
Multiply-defined line number 
Multiply-defined variable 
Illegal input variable 

Seek out of range 

Missing data statement 
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Windowing and System Errors 


Code 


183 
184 
185 
186 
187 
188 
189 
190 
191 
192 
193 
194 
195 
196 
197 
198 
199 
200 
201 
202 
203 
204 
205 
206 
207 
208 
209 
210 
211 
212 
213 
214 
215 
216 
217 
218 
219 
220 
221 
223 


Meaning 


Illegal window type 

Window already defined 

Font not found 

Stack overflow 

Illegal argument 

(unused) 

Illegal coordinates 

Internal integrity check 
Buffer size is too small 
Illegal command 

Screen or window table is full 
Bad/undefined buffer number 
Illegal window definition 
Window undefined 

(unused) 

(unused) 

(unused) 

Path table full 

Illegal path number 
Interrupt polling table full 
Illegal mode 

Device table full 

Illegal module header 
Module directory full 
Memory full 

Illegal service request 
Module busy 

Boundary error 

End of file 

Returning non-allocated memory 
Non-existing segment 

No permission 

Bad path name 

Path name not found 
Segment list full 

File already exists 

Illegal block address 

Phone hangup data carrier detect lost 
Module not found 

Suicide attempt 
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Code 


224 
226 
227 
228 
229 
230 
231 
232 
233 
234 
235 
237 
238 
239 
240 
241 
242 
243 
244 
245 
246 
247 
248 
249 
250 
251 
252 
253 


Meaning 


Illegal process number 

No children, can’t wait for nonexistent child process 
Illegal SWI code 

Process aborted, signal 2 

Process table full, can’t fork a process 
Illegal parameter area 

Known module 

Incorrect module CRC 

Signal error 

Non-existent module 

Bad name 

System RAM full 

Unknown process ID 

No task number available 

Illegal unit error 

Bad sector number 

Write protected disk 

CRC error 

Read error 

Write error 

Not ready, device not ready 

Seek error 

Media full 

Wrong type, incompatible media type 
Device busy 

Disk ID change, disk changed with open files 
Record is locked out 

Non-sharable file busy 


Appendix B 


The Inkey Program 


Assembly Language Listing of Inkey 


An assembled version of Inkey is included on the CONFIG/ 
BASICO9 diskette. Use Inkey from BASICO9 with the RUN 


statement. 


EEKEKEEEEEEEHEHRE EER EEEESE 


* INKEY - a subroutine for BASICO9 by Robert Doggett 


* Called by: RUN INKEY(StrVar) 

' RUN INKEY(Path, StrVar) 
* INKEY determines if a key has been typed on the given path 

* (Standard Input if not specified), and if so, returns the next 
* character in the String Variable. If no key has been typed, the 


a 


Ed 


0021 
0081 


0000 87CDOOSE 


000) 496E6B6S 
0000 

0000 

0002 

0004 

0006 

0008 

000A 

0000 

OO0E 

W012 3064 


Ce: OS) © (SS S&S 


NAM 
IFP 1 
USE 
ENDC 


TYPE set 
REVS set 


mod 


InKeyNam fcs 


org 
Return  rmb 
PCount rmb 


Param]  rmb 
Length! rmb 
Parame  rmb 
Lengthe rmb 
E$Param equ 
DLZE equ 
InkeyEnt leax 


null string is returned, If a path is specified, it must be 
either type BYTE or INTEGER, 


INKEY 

/DO/DEFS/OS9DEFS 
SBRTN+OBUCT 
REENT+1 

InKeyEnd, InkeyNam, TYPE ,REVS 
»InkeyEnt,s12e 

“Inkey" 

0 Parameters 

2 Return addr of caller 
2 Num of params following 
2 1st param addr 

2 size 

2 end param addr 

2 size 

$38 

* 

Param! ,S 
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0014 £EC62 ldd Pcount,S Get parameter count 
0016 10830001 cmpd #| just one parameter? 
O01A 2727 beq InKeyed .. Yes; default path A=@ 
O01C 10830002 cmpd #2 Are there two params? 
0028 2635 bne ParamErr No, abort 

Q022 ECF804 ldd [Paramt,S] Get path number 

00825 AE66 Idx Length! ,9 

O027 301F leax RP byte variable? 

9029 2706 beq Inkey18 .. Yes; (A)=Path number 
Q02B 301F leax te Integer? 

002D 2628 bne ParamErr . No; abort 

Q02F 1F98 tfr B,A 

0031 3068 Inkey10 leax Parame,S 

$033 EEd2 InKey2@ = ldu ey length of string 

0035 AE84 Idx Q ,X addr of string 

0037 COFF ldb #$FF 

0039 £784 stb 0,X Initialize to null str 
§03B 11830002 cmpu #2 at least two-byte str? 
Q03F 2502 blo Inkey30 No 

0041 E701 stb tan put str terminator 
0043 Cod' InKey3@ = 1db #55.Ready 

0045 103F8D 0$9 1$GetStt is there any data ready? 
0048 2508 bcs Inkey3@ . No; exit 

004A 10860001 ldy # 

O04E 103F89 0$9 I$Read Read one byte 

0051 39 rts returns error status 
0052 CtF6 InkKey9@ = cmpd #ESNotRdy 

0054 2603 bne InkeyErr 

0056 39 rts (carry clear) 

9057 C638 ParamErr ldb #E$Param Parameter Error 

9059 43 InkeyErr coma 

Q05A 39 rts 

Q05B 1A6916 emod 

OO5E InkeyEnd equ t 


Index 


ABS command 11-4 
absolute value 11-4 
accessing 
files 8-1, 10-8 
lines (editor) 4-4 - 4-5 
OS-9 commands from 
BASIC 3-7 
ACS command 11-5 
adding lines 4-10 - 4-12 
addition 7-3 - 7-4 
ADDR command 11-6 
address 
of variable 6-8, 11-6 
space 11-6 
advantages of BASICO9 14-1 - 
1-2 
ALPHA (medium-res) 9-9, 
9-13 
alphanumeric 
mode 9-10 
screen 9-9, 9-13, 9-30 
ALT key 1-6, 9-4 
AND 
command 11-8 
logical AND 
command 11-84 
operator 17-3, 7-4, 7-7 
appending 
data to files 8-3 
strings 7-6 
ARC command (high-res) 
9-50 
arccosine 11-5 
arcsine 11-10 
arctangent 11-11 
arithmetic 
function speed 12-2 
operators 7-3 
array 6-9 - 6-13 
address 11-6 
element 6-9 
index 11-12 
with random access 
files 8-9 


ASC command 11-9 
ASCII 
character value 11-18 
codes 9-1 - 9-6, 11-9 
ASN command 11-10 
assign 
variable storage 11-31 
variable values 11-78 
variables (debug) 5-3 
ATN command 11-11 
auto execution 3-8 
automatic error checking 1-4 


background color 
high-resolution 9-34 
medium-resolution 9-11 
backslash 1-6 
BAR command (high-res) 
9-52 - 9-53 
base 10 logarithm 11-83 
BASE command 11-12 - 
11-13 
BASIC09 
advantages 1-1 - 1-2 
graphics with 128K 
9-37 - 9-39 
quitting 1-5, 3-1 
starting 1-2 - 1-4 
starting windows 
from 9-39 - 9-41 
beep 9-54 
beginning debug 5-1 
BELL command (high-res) 
9-54 
binary data record 11-58 
BLNKOFF command (high- 
res) 9-55 
BLNKON command (high- 
res) 9-55 
BOLDSW command (high- 
res) 9-56 
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Boolean 
data 6-1 - 6-2, 6-5 
functions 7-10 
OR 11-106 
TRUE 11-175 - 11-176 
value 11-51 
border color (high-res) 9-58, 
9-65 
BORDER command (high- 
res) 9-58 
BOX command 9-60 - 9-61 
brace characters 1-6 
BREAK 
command (debug) 5-2 
key 1-6, 5-2 
breakpoint (debug) 5-2 
buffer 
defining 9-78 
font (high-res) 9-94 
get/put (high-res) 9-117 
group (high-res) 9-101 
pattern (high-res) 9-111 
button, joystick (medium- 
res) 9-9, 9-22 
BYE command 1-5, 3-1, 10-9, 
11-14 
byte 
data type 6-1 - 6-2 
numeric range 6-2 
retrieval from a file 8-5 
type functions 7-9 


calculate 
low-res characters 9-5 
sine 11-154 
square root 11-158 
call a shell command 10-9 
carriage return 1-7 
high-resolution 9-67 
CHAIN command 11-15 - 
11-16 
changing 
a procedure name 10-9 
color (high-res) 9-65 - 
9-66 


changing (cont’d) 
color (medium-res) 9-9 
directory 3-1, 3-7, 10-9, 
11-17, 11-19 
file pointer 11-148 
procedures 1-4 
scale (high-res) 
9-122 
text 4-7 - 4-9 
text (editor) 4-1 - 4-2 
working area (high-res) 
9-76 
character 
backslash 1-6 
blink (high-res) 
braces 1-6 
brackets 1-6 
fonts 9-43 - 9-44 
graphic 1-6 
high-resolution 9-8, 9-94 
reverse video (high- 
res) 9-120 
tilde 1-6 
underline (high-res) 
9-126 
underscore 1-6 
up arrow 1-6 
value 11-18 
vertical bar 1-6 
CHD command 3-1, 3-7, 
10-9, 11-17, 11-19 
CHX command 3-1, 3-7, 
10-9, 11-17 - 11-19 
CIRCLE 
high-resolution 9-62 
medium-resolution 9-9, 
9-15 - 9-16 
CLEAR 
high-resolution 9-64 
key 1-6 
medium resolution 9-9, 
9-17 
close a window (high-res) 
9-83 - 9-84 


9-121 - 


9-55 


CLOSE command 11-20 - 
11-21 
code 
ASCII 9-1 - 9-6, 11-9 
error 11-43, Al - A4 
COLOR 
high-resolution 9-65 
medium resolution 9-9, 
9-18, 9-19 
color 
codes (medium-res) 
9-10 - 9-11 
default 9-79 
high-resolution 9-31, 
9-109 - 9-110 
medium-resolution 9-11 
of border (high-res) 
9-58 - 9-59 
of pixel (medium-res) 
9-28 - 9-29 
of screen (medium- 
res) 9-26 
palette default 9-79 
set (medium-res) 9-18 - 
9-19 
command 
interpreter 3-1 
line storage area 3-3 
line symbols 11-2 
lines using spaces 2-2 
mode 1-3 
mode reference 10-9 
commands 
by type 10-7 
configuring (high-res) 
9-47 
debug 10-11 
drawing (high-res) 
editing 10-10 
executing OS-9 3-7 - 3-8 
font (high-res) 9-49 
quick reference 10-1 - 
10-6 


4 


system 3-l 


9-46 


Index 


commands (cont’d) 
text/cursor (high-res) 
9-48 
using wildcards 3-5 
window (high-res) 9-45 
comments in a procedure 
11-1385 - 11-136 
compile procedure 3-1, 3-8 - 
3-9, 10-9 
compiler, multipass 
compiling 
procedures 1-5 
saving space 1-2 
complement, logical 11-96 
complex 
data structure 1-2, 
8-11 - 8-12, 11-177 - 
11-178 
data types 
6-16 
compressed procedures 
concatenation 7-3 
condensed procedures 3-1 
configuring commands (high- 
res) 9-47 
constant expressions 
constants, string 6-7 
control key 1-6 
converting 
data types 6-6, 7-2 
numeric types 11-54, 
11-71, 11-162 - 11-163 
string data 11-181 - 
11-183 
copying structure elements 
6-16 
COS command 11-22 
cosine 11-22 
create 
data types 11-177 
overlay windows (high- 
res) 9-107 
procedures 2-1 
random access files 8-6 - 
8-9 
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6-1, 6-13 - 
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create (cont’d) 
sentences procedure 4-3 
sequential files 8-2 - 8-3 
windows 9-35 - 9-36 
CREATE command 8-2 - 8-3, 
8-6 - 8-7, 11-23 - 11-24 
CRRTN command (high- 
res) 9-67 
CTRL key 1-6 - 1-7 
CTRL-BREAK key 
sequence 1-6, 3-1 
CURDWN command (high- 
res) 9-68 
CURHOME command 9-69 
CURLFT command (high- 
res) 9-70 
CUROFF command (high- 
res) 9-71 
CURON command (high- 
res) 9-72 
current command line 1-7 
CURRGT command (high- 
res) 9-73 
cursor 
graphics (high-res) 9-95, 
9-119 
graphics (medium- 
res) 9-27 
invisible (high-res) 
movement 1-6, 9-67 - 
9-68, 9-74 - 9-75 
position 11-116 
CURUP command (high- 
res) 9-74 
CURXY command (high- 
res) 9-75 
CWAREA command (high-res) 
9-76 - 9-77 


9-f1 


data 
changing in sequential 
file 8-4 
complex types 6-1, 
6-13 - 6-16 
constants 6-6 - 6-7 


data (cont’d) 

directory 3-7 

items 6-1 

manipulation 7-1 - 7-2 

meaning 6-1 

pointer 11-140 

reading 11-132 - 11-133 

structure 1-2, 11-177 - 
11-178, 12-2 

structure address 

to files 8-1 

type, Boolean 6-5 

type, byte 6-2 

type, conversion 7-2 

type, integer 6-3 

type, real 6-3 - 6-4 

types 6-1, 10-8, 11-177 - 
11-178, 12-1 

types, creating 11-177 - 
11-178 


11-6 


DATA command 11-25 - 
11-26 
DATE$ command 11-27 - 
11-28 
day 11-27 
deallocate 
buffer (high-res) 
9-102 
graphics memory 9-30 
windows (high-res) 
9-83 - 9-84 


9-101 - 


debug 
beginning 5-1 
breakpoint 5-2 
commands 5-2 - 5-4, 
10-11 
display procedure 65-3 
quitting 5-3 
starting 5-1, 5-4 - 5-5, 
11-112 
tracing 5-4 
debug command 


Index 


debug command (cont'd) 
DEG 5-2 
DIR 5-3 
LET 5-3 
LIST 5-3 
PRINT 5-3 
Q 5-3 
RAD 5-2 
STATE 5-3 
STEP 5-4 
TROFF 5-4 
TRON 5-4 
default colors 9-79 
DEFBUFF command (high- 
res) 9-78 
DEFCOL command (high- 
res) 9-79 
define a window (high-res) 
9-86 - 9-87 
defining string variables 6-4 
DEG command 11-29 
degrees, selecting in debug 
5-2, 11-29 
DELETE command 11-30 
delete line 1-6, 2-2 
editor 4-2 
high-resolution 9-80, 
9-92 
deleting 
procedure lines 4-6 - 4-7 
procedures 3-6 
delimiter 4-8 
in sequential files 8-2 
symbols (editor) 4-8 
DELLIN command (high- 
res) 9-80 
device path 11-104 
DIM command 11-31 - 11-32 
DIM statement 6-2, 11-31 
DIR 
command 3-1 -3-2, 10-9 
debug 5-3 
file access 8-1 


directory 
change 3-1, 3-7, 11-17, 
11-19 
data 3-7 
execution 3-7 
ROOT 3-7 
disassembled procedure 3-3 
disk file 8-1 
creation 11-23 
deletion 11-30 
display 
a formatted listing 10-9 
a window 1-6, (high- 
res) 9-123 - 9-124 
clearing (medium- 
res) 9-17 
current command 
line 1-7 
last line 1-7 
previous window 1-6 
procedure 3-1 
procedure from debug 
5-3 
procedure 
information 3-1, 10-9 
text 11-119 - 11-120 
workspace size 3-1, 10-9 
division 7-3 
remainder 11-93 
DO command 11-34 
dot, graphics (medium-res) 
9-28 - 9-29 
draw 
a circle (high-res) 
a circle (medium-res) 
9-9, 9-15 - 9-16 
a line (high-res) 
9-104 
an ellipse 9-88 - 9-89 
arcs (high-res) 9-50 - 
9-51 
command (high-res) 
9-46, 9-81 - 9-82 
pointer (high-res) 


9-62 - 


9-103 - 


9-125 
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draw (cont'd) 
pointer (medium-res) 
9-12 
lines (medium-res) 
9-24 - 9-25, 9-103 
rectangles (high-res) 
9-52 - 9-53, 9-60 - 9-61 
DWEND command (high- 
res) 9-83 - 9-84 
DWPROTSW command (high- 
res) 9-85 
DWSET command (high- 
res) 9-86 - 9-87 


edit 
compiler 3-1 
mode, entering 1-4 
pointer 4-1 
terminating 2-3 
EDIT command 3-1, 10-9 - 
10-10 
editor 4-1 - 4-9 
element 6-9 
elements 
of a structure, 
copying 6-16 
of an array 6-9 
ELLIPSE command (high- 
res) 9-88 - 9-89 
ELSE command 11-35 
END command 11-36 - 11-37 
end execution 11-14 
end-of-file 
message 1-6 
test 11-42 
ENDEXIT command 11-38 
ENDIF command 11-39 
ENDLOOP command _ 11-40 
ENDWHILE 11-41 
ENTER 
command (editor) 4-1 
in the editor 4-4 
key 1-7 


entering 
debug 5-4 - 5-5 
the edit mode 1-4 
EOF command 11-42 
equal operator 7-5 
erase 
a disk file 11-30 
procedures 3-1, 11-72 
to end of line 9-90 
to end of window 9-91 
EREOLINE command (high- 
res) 9-90 
EREOWNDW command (high- 
res) 9-91 
ERLINE command (high- 
res) 9-92 
ERR command 11-43 - 11-44 
error 
checking, automatic 1-4 
code 11-438 - 11-44, 
A-1 - A-4 
ina program line 2-2 
simulation 11-45 - 11-46 
trapping 11-97 - 11-99 
ERROR command 11-45 
escape function 1-6 
establishing a window 9-32, 
9-41, 9-86 - 9-87 
evaluating expressions 
7-2 
evaluation, order of 
operators 7-4 - 7-5 
examine 
aprocedure 4-4 
memory 11-113 
exclusive OR 11-187 - 11-188 
EXEC file access 8-1 
executable procedures 3-8 
execute 
a procedure 2-3, 3-1, 
3-8, 10-9, 
11-145 - 11-147 
an OS-9 command 3-1, 
3-7 - 3-8 


7-1 - 


execute (contd) 
modules 
procedure lines 
execution 
automatic 3-8 - 3-9 
directory change 3-1, 
3-7 
speed 1-1 
stepping 5-5 - 5-6 
stopping 11-161 
termination 11-14 
EXITIF/THEN/ENDEXIT 
commands 11-47 
exiting 
BASICO9 1-5 
debug 5-3 
EXP command 11-50 
exponent, natural 11-50 
exponentiation 7-3 
expression 7-1 


11-15 - 11-16 
11-34 


FALSE 
command 11-51 - 11-52 
value 7-7 

faster loops 12-2 

file 

listing procedures to 3-4 

path 11-104 

pointer 8-3, 8-5, 

11-148 - 11-149 
pointer, rewinding 8-11 
retrieving bytes 8-5 
writing 11-129 - 

11- 130, 11-185- 

11-186 

8-1 
accessing 8-1, 10-8 
appending data 8-3 
closing 11-20 - 11-21 
creating random 

access 8-6 - 8-9 


files 


creating sequential 8-2 - 
8-4 

creation 11-23 - 11-24 

opening 11-104 - 11-105 


Index 


files (cont'd) 
random access’ 8-5 - 
8-11 
writing to 8-3 
FILL command (high-res) 
9-93 
filled rectangles (high-res) 
9-52 - 9-53 
finding 
graphics screen (medium- 
res) 9-20 - 9-21 
lines 4-5 
fire button (medium-res) 
FIX command 11-53 
FLOAT command 11-54 
FONT command (high-res) 
9-94 
font-handling commands (high- 
res) 9-49 
fonts 9-438 - 9-44 
FOR/NEXT loops 
11-160 
FOR/NEXT/STEP 
commands 11-55 - 11-57 
foreground color 
high resolution 9-65 - 
9-66 
medium resolution 9-11, 
9-18 - 9-19 
fork a shell 11-152 - 11-1538 
to a window 9-32 
format 
medium resolution 9-10 
of screen (medium- 
res) 9-26 
of windows 9-34 
formatted procedure 3-1 
formatting 
display screen 11-180 
screen display 11-122 - 
11-127 
functions 7-7 - 7-10 
Boolean type 7-10 
byte type 7-9 
integer type 7-9 


9-22 


11-159 - 
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functions (cont'd) 
logical 7-10 
numeric type 7-9, 10-7 
real type 7-8 
string 7-10, 10-7 
trace 5-5 - 5-6 
transcendental 10-7 
GCOLR (medium-res) 9-9 
GCSET command (high- 
res) 9-95 
GET command 8-5, 11-58 
high-resolution 9-96 
GET/PUT buffer 9-78 
high-resolution 9-101 
GET/PUT commands (high- 
res) 9-47 
global symbol (editor) 4-5 
GLOC (medium-res) 9-9, 
9-20 
GOSUB/RETURN 
commands 11-61 
GPLOAD command (high- 
res) 9-98 
graphics 
characters 1-6 
cursor (high-res) 
9-119 
cursor (medium-res) 
9-9, 9-27 
high-resolution 9-31 - 
9-126 
levels 9-1 
logic functions 9-105 
low resolution 9-4 - 9-8 
medium-resolution 9-8 - 
9-30 
memory deallocate 9-30 
number of levels 1-2 
pattern (high-res) 
9-111 - 9-112 
pointer (high-res) 9-42 
screen (medium-res) 
9-26 


9-95, 


graphics (cont'd) 
screen location (medium- 
res) 9-20 - 9-21 
window 9-35 - 9-36 
with 128K 9-387 - 9-40 
greater than 7-3, 7-5 
grid format (medium-res) 
9-10 
group 
buffer (high-res) 
9-102 
number 9-78 


9-101 - 


hardware window 9-32 - 9-35 
high-resolution 9-31 - 9-126 
adapter 9-22 
characters 9-8 
colors 9-109 - 9-110 
quick reference 9-44 - 
9-49 
text 9-42 
hour 11-27 


I-Code 3-3, 12-1 
IF/THEN/ELSE loop 11-35 
IF/THEN/ELSE/ENDIF 
commands 11-63 - 11-65 
image, get (high-res) 9-98 
immortal shell 9-32 
initialize a disk file 11-23 - 
11-24 
INIZ command 9-32 - 9-33 
Inkey program B-1 - B-2 
INPUT command 8-5, 11-68 - 
11-70 
input/output 12-4 
insert 
a line (high-res) 
9-100 
text (editor) 4-1 
INSLIN command (high- 


9-99 - 


res) 9-99 - 9-100 
INT command 11-71 
integer 


constants 6-7 


Index 


integer (cont’d) 
data type 6-1, 6-2, 6-3 
functions 7-9 
numeric range 6-2 
interfacing with OS-9 1-1 
invisible cursor (high-res) 
9-71 


JOYSTK 9-9, 9-22 
jump 
to line number 11-102 - 
11-103 
to subroutine 11-100 - 
11-101 


key 
ALT 1-6, 9-4 
BREAK 1-6, 5-2 
CLEAR 1-6 
CTRL 1-6-1-7 
ENTER 1-7 
key sequence 
CTRL with other 
keys 1-6 -1-7 
SHIFT with other 
keys 1-6 
keyword 11-1 
KILL command _ 3-1, 3-6, 
10-9, 11-72 - 11-738 
KILLBUFF command (high- 
res) 9-101 
killing a procedure 3-6 


LAND command 11-74 - 
11-75 

language modules 1-5 

last line, displaying 1-7 

left brace 1-6 

left bracket 1-6 

LEFT$ command 11-76 

LEN command 11-77 

length of string variables 6-4 

less than 7-3 - 7-4, 7-5 


LET command 6-8, 11-78 - 
11-79 
debug 5-3 
LINE (medium-res) 9-9 
line 
accessing (editor) 4-5 
adding 4-10 - 4-12 
adding (editor) 4-10 
erasing 9-90 
see also line, deleting 
inserting (high-res) 
9-99 - 9-100 
jumping to 11-102 - 
11-103 
numbers 4-5 
renumbering 4-2, 4-10 
LINE command 
high-resolution 9-103 
medium-resolution 9-24 
line deleting 1-6, 2-2, 9-92 
editor 4-2 
high-resolution 9-80 
in procedures 4-6 - 4-7 
LIST command 3-1, 3-2 - 3-5, 
4-6, 10-9 
listing 
procedures 3-2 - 3-5, 
6-6, 10-9 
procedure lines 
(editor) 4-2 
toa file 3-4 
to a printer 3-4 
LNOT command 11-80 - 
11-81 
LOAD command _ 3-1, 3-6, 
10-9 
loading 
a buffer (high-res) 
BASICO9 1-2 - 1-4 
procedures 3-1, 3-6, 
10-9 
window image (high- 
res) 9-101 - 9-102 
local variable 6-7 
LOG command 11-82 


9-98 
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LOG10 command 11-83 
logarithm 11-82, 11-83 
logic comparison 6-5 
LOGIC command (high- 
res) 9-105 - 9-106 
logical 
AND 11-8, 11-74 - 
11-75 
block (file) 8-1 
complement 11-96 
functions 7-10 
NOT 11-80 - 11-81, 
11-96 
operators 7-7 
OR 11-87 - 11-88 
XOR 11-89 - 11-91 
loop 
EXITIF/ENDEXIT/ 
ENDEXIT 11-38, 
11-47 - 11-49 
FOR/NEXT 11-55, 
11-57, 11-95, 
11-159 - 11-160 
IF/THEN/ELSE/ENDIF 
11-35, 11-39, 
11-63 - 11-65 
LOOP/ENDLOOP 
11-40, 11-84 - 11-86 
REPEAT/UNTIL 
11-137 - 11-139, 
11-179 
WHILE/DO/ 
ENDWHILE 11-34, 
11-41, 11-183 - 11-184 
loop repetition 11-95 
LOR command 11-87 - 11-88 
low-resolution 9-1 - 9-7 
LXOR command 11-89 - 
11-91 


math 1-2 
medium-resolution 9-8 - 9-30 
format 9-10 - 9-11 
MEM command 1-8 - 1-4, 
3-1, 10-9 
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memory 
changing 11-116- 
11-117 
examining 11-113 - 
11-114 


in the workspace 3-1 
requesting 1-3 - 1-4 
saving 1-2 
size 1-3, 1-4 
message, end-of-file 1-6 
MID$ command 11-92 
minimizing storage 12-1 
minutes 11-27 
mistakes in program lines 
mixing data types 7-2 
MOD command 11-93 
MODE (medium-res) 9-9, 
9-26 
modes 
command 1-3 
edit 1-4 
module 
execution 11-15 
high-resolution 9-31 
medium-resolution 9-8 - 
9-9 
modulus 11-93 11-94 
month 11-27 
mouse (medium-res) 9-22 
MOVE (medium-res) 9-9, 
9-27 
move cursor 1-6 
high-resolution 9-68, 
9-70, 9-73 - 9-75 
move 
backward (editor) 4-5 
draw pointer (high- 
res) 9-125 
graphics cursor (high- 
res) 9-95 
the edit pointer 4-1 
multipass compiler 12-1 
multiplication 7-3 - 7-4 


natural exponent 11-50 
negation 7-3 
nesting order (debug) 5-3 
NEXT command 11-95 
NOT command 11-96 
not equal to 7-3, 7-4, 7-5 
NOT, logical 11-80 - 11-81 
operator 7-4, 7-7 
null constants 6-9 
numbers for lines 4-5 
numeric 
constants 6-6 
data conversion 11-162 - 
11-163 
data types 12-1 - 12-2 
functions 10-7 
type conversion 11-54, 
11-71 
type functions 7-9 


ON ERROR/GOTO 
command 11-97 - 11-99 
ON/GOSUB command 
11-100 - 11-101 
ON/GOTO command 11-102 - 
11-103 
OPEN command 8-3, 
11-104 - 11-105 
operands 7-2 
operators 7-1 
arithmetic 7-3 - 7-4 
equal 7-5 
greater than 7-5 
hierarchy of 7-4 
less than 7-5 
logical 7-7 
relational 7-5 - 7-6 
string 7-6 
types 7-3 
unequal 7-5 
OR 
command 11-106 
logical 11-87 - 11-88 
operator 7-7 


Index 


order 
of nesting (debug) 5-3 
of operators 7-4 - 7-5 
OS-9 commands 11-152 
accessing 3-7 - 3-8 
overlay windows 9-41, 9-107 - 
9-108 
OWSET command (high- 
res) 9-107 - 9-108 


PACK command 3-1, 3-8, 3-9, 
10-9, 12-4 
paint (high-res) 9-93 
PALETTE command (high- 
res) 9-109 - 9-110 
palette 
default colors 9-79 
high-resolution 9-34 - 
9-35 
registers 9-35 
PARAM command 6-8, 
11-108 - 11-111 
passing variables 6-8, 
11-108 - 11-111 
path 
input 11-68 
opening 11-104 - 11-105 
PATTERN command (high- 
res) 9-111 - 9-112 
PAUSE command. 5-5, 11-112 
PEEK command 9-20, 
11-113 - 11-114 
PI command 11-115 
pixel 9-34 
color (medium-res) 
9-28 - 9-29 
set (high-res) 9-113 - 
9-114 
plus sign 7-6 
POINT 
high-resolution 9-118 - 
9-114 
medium-resolution 9-10, 
9-28 - 9-29 
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pointer 
draw (hi-res) 9-42, 
9-125 
draw (medium-res) 
edit 4-1 
file 8-5 
graphics 9-42 
READ 11-140 
POKE command 9-20, 11-116 
POS command 11-118 
position 
graphics cursor (medium- 
res) 9-9 
of arecord ina file 8-5 
of cursor 11-118 
power of 2 11-157 
predefined windows 
9-33 
PRINT command 11-119 - 
11-120 
debug 5-3 
PRINT USING command 
11-122 - 11-128, 
11-180 - 11-182 
printer, listing files 3-4 


9-12 


9-32 - 


printing (tabs) 11-166 - 
11-167 
procedure 
changing 1-4 
comments 11-135 - 
11-136 


compilation 10-9 
compiling 1-5 
compressing 12-1 
condensing 3-1 
data size 3-2 
deleting 3-6 
disassembling 3-3 
display 3-1 
displaying information 
about 3-1 
erasing 3-1, 11-72 - 
11-73 
examining 4-4 
executing 1-5 
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procedure (cont'd) 
execution 2-3, 3-1 
grouping 1-4 
listing 3-2 - 3-3, 4-6 
loading 3-6 
renaming 3-2 
returning from 11-141 
saving 3-1, 3-5 - 3-6, 
10-9 
size 3-2 
suspending 11-112 
terminating 11-36 - 
11-37, 11-161 
tracing 11-174 
writing 2-1 - 2-2 
procedures 
executable 3-8 
executing 11-145 - 
11-147 
loading 3-1 
program 
execution termination 
1-6 
mistakes 2-2 
modular 1-1 
proportional text (high-res) 
9-115 - 9-116 
PROPSW command (high- 
res) 9-115 - 9-116 
protect window switch (high- 
res) 9-85 
PUT command 8-5, 8-6, 
9-117 - 9-118, 
11-129 - 11-130 
PUTGC command 9-119 


QUIT (medium-res) 
9-30 
quit 


9-10, 


BASICO9 1-5, 3-1 
debug 5-3 
the editor 2-3, 4-2 


RAD command 5-2, 11-131 
radians 5-2, 11-131 


Index 


random access files 8-5 - 8-11 
and arrays 8-9 - 8-11 
creating §&-6 - 8-9 

random value 11-143 - 

11-144 
range of numbers 6-2 
READ 8-4, 11-25, 11-132 - 
11-133 
file access 8-1 

read 
input 11-66 - 11-70 
pixel color (medium- 

res) 9-9 

read arecord 11-58 - 11-60 

real 
constants 6-7 
data type 6-1 - 6-4 
functions 7-8 
number conversion 

11-71 
number range 6-2 
number rounding 11-53 

record 8-2 
binary data 11-58 
position 8-5 

rectangle, drawing (high- 

res) 9-52 - 9-53, 9-60 - 
9-61 
reduce memory size 1-4 
registers palette 9-35, 9-109 - 
9-110 

relational operators 7-5 - 7-6 

relative storage area 3-3 

REM command 11-135 - 

11-136 
remainder (division) 
removing 

disk files 

procedures 
11-72 

spaces 11-172 - 11-1738 

RENAME command 3-1 

renaming procedures 3-2 

renumbering lines (editor) 

4-2, 4-10 


11-93 


11-30 
3-6, 10-9, 


REPEAT/UNTIL 
commands 11-137 - 
11-139, 11-179 
requesting memory 1-3 - 1-4 
reset file pointer 11-148 - 
11-149 
RESTORE command 11-140 
retrieving bytes from a file 
8-5 
RETURN command 11-141 
returning 
from subroutine 11-61 - 
11-62 
to OS-9 10-9 
reverse video (high-res) 9-120 
REVON command (high- 
res) 9-120 
rewind a file 8-11 
right brace 1-6 
right bracket 1-6 
RIGHT$ command 11-142 
ring bell 9-54 
RND command 11-148 - 
11-144 
ROOT directory 3-7 
rounding a real number 
11-53 
RUN command _ 3-1, 6-8, 10-9, 
11-145 - 11-147 


SAVE command 3-1, 3-5, 10-9 
saving 
a window area 9-96 - 
9-97 
graphic images (high- 
res) 9-117 - 9-118 
memory 1-2 
procedures 3-1, 3-5 
space by compiling 1-2 
SCALESW command (high- 
res) 9-121 - 9-122 
screen 
alphanumeric 9-30 
blink (high-res) 9-55 
clearing (high-res) 9-64 
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screen (cont'd) 

clearing (medium- 
res) 9-9, 9-17 

color (medium-res) 

display 11-122 

format (medium-res) 
9-26 

formatting 11-180 

location (medium-res) 
9-20 - 9-21 

resolution 9-31 

selecting (medium- 


9-26 


res) 9-13 - 9-14 
switching (medium- 
res) 9-9 
searching 
for text (editor) 4-2, 4-9 
in strings 11-164 - 
11-165 
seconds 11-27 


SEEK command 11-148 - 
11-149 
select a window 9-32 - 9-33 
SELECT command (high- 
res) 9-123 - 9-124 
selecting memory 1-3 
sending a carriage return 
9-67 
sentence-creating 
procedure 4-3 
sequential file writes 
11-185 - 11-186 
SETDPTR command (high- 
res) 9-125 
setting 
a point (medium-res) 
9-10, 9-28 - 9-29 
border color (high- 
res) 9-58 - 9-59 
color (medium-res) 9-18 
pixel (high-res) 9-113 - 
9-114 
READ pointer 11-140 
screen (medium-res) 9-9 
SGN command 11-150 - 
11-151 


14 


SHELL command 11-152 - 
11-153 

shell commands 10-9 

SHIFT-« key sequence 1-6 

SHIFT-BREAK key 
sequence 1-6 

SHIFT-CLEAR key 
sequence 1-6 

show text 11-119 - 11-121 

sign of a value 11-150 - 
11-151 

simulating an error 
11-46 

SIN command 11-154 

sine 11-154 

single-diménsioned array 
6-9 - 6-10 

SIZE command 11-155 - 
11-156 

size 


11-45 - 


data 3-2 

memory 1-3 

procedure 3-2 
space 

removing 11-172 - 

11-173 

saving by compiling 1-2 
spaces in command lines 2-2 
special keys 1-5-1-7 
speed 

of arithmetic 

functions 12-2 

of execution 1-1 
SQ command 11-157 
SQR/SQRT commands 
square root 11-158 
starting 

a shellin a window 9-36 

BASICO9 1-2 - 1-4 
STATE command (debug) 5-3 
statements 10-7 
status of joystick (medium- 

res) 9-22 - 9-23. 
STEP command. 5-4, 11-159 - 
11-160 


11-158 


step rate (debug) 5-4 
stepping through 
procedures 5-5 - 5-6 
STOP command 11-161 
stop program execution 1-6 
storage 
area of command 
lines 3-3 
minimization 12-1 
of variables 11-31 - 
11-33 
storing 
data 11-25 - 11-26 
in memory 11-116 - 
11-117 
STR$ command 11-162 - 
11-163 
string 
constants 6-7 
data conversion 11-181 - 
11-182 
data type 6-1 - 6-2 
functions 10-7 
length 6-4, 11-77 
operators 7-6 
storage 6-5 
variables 6-4 - 6-5 
strings 
appending 7-6 
portioning 11-76, 11-92, 
11-142 
searching 11-164 
structured programming 1-1 
structures, complex data 
8-11 - 8-15 
subroutine 
commands 11-61 - 11-62 
jumps 11-100 - 11-101 
SUBSTR command 11-164 - 
11-165 
substrings 11-92 
subtraction 7-3 - 7-4 
suspending execution 11-112 
switching screens (medium- 
res) 9-9, 9-13 - 9-14 


Index 


symbolic debugging 5-1 
syntax 11-1 
system 
commands 3-1 
interfacing 1-1 


TAB command 11-166 - 
11-167 
TAN command 11-168 
tangent 11-168 
terminating 
a procedure 11-36 - 
11-37, 11-161 
the editor 4-2 
test for end-of-file 11-42 
text 
changing 4-2, 4-7 - 4-9 
characters (high-res) 
9-94 
display 11-119 - 11-121 
fonts 9-43 - 9-44 
formatting 11-122 - 
11-128 
high-resolution 9-42 - 
9-44 
proportional 9-115 - 
9-116 
searching 4-2, 4-9 
cursor commands (high- 
res) 9-48 
three-dimension arrays 6-13 
tilde 1-6 
time 11-27 - 11-28 
tracing 
execution 5-4 - 5-6, 
11-174 
transcendental functions 10-7 
trapping errors 11-97 - 11-99 
TRIM$ command 11-172 - 
11-173 
TROFF command (debug) 
5-4, 11-174 
TRON command 5-4 - 5-6, 
11-174 
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TRUE command 11-175 - 
11-176 
turning off the cursor 9-71 
two-dimension array 6-9 
type 
conversion 6-6, 7-2 
mismatch 6-6 
of data 6-1 - 6-16, 10-8 
of file access 8-1 
of operators 7-3 
TYPE command 8-12, 
11-177 - 11-178 


underscore 1-6 

UNDLNOFF command (high- 
res) 9-126 

UNDLNON command (high- 
res) 9-126 

unequal 7-5 

UNTIL 11-1387 - 11-139, 
11-180 

up arrow 1-6 

UPDATE 8-1, 8-4 

USING command 11-180 - 
11-182 

using debug 5-4 - 5-5 


VAL command 11-181 - 
11-182 
value 
absolute 11-4 
Boolean 11-51 - 11-52 
random 11-143 - 11-144 
variable 
address 6-8, 11-6 
initialization 6-8 
local 6-7 
passing 6-8 - 6-9, 
11-108 - 11-111 
size 11-155 - 11-156 
storage 11-31 - 11-33 
value of 11-78 - 11-79 
variables 11-2 
assigning (debug) 5-3 


local 6-7 
string 6-4 - 6-5 
vector 6-13 
vertical bar 1-6 
video 
address (medium-res) 
reverse (high-res) 9-120 
visible cursor (high-res) 9-72 


WCREATE command 9-33 - 
9-34 
WHILE/DO/ENDWHILE 
loop 11-34, 11-41, 
11-180 - 11-181 
whole number, range 6-2 
wildcard 
editor 4-1 
using with commands 
3-5 
window 
area, saving 9-96 - 9-97 
commands (high-res) 
9-45 
deallocating (high- 
res) 9-83 - 9-84 
defining (high-res) 
9-86 - 9-87 
display 1-6, 9-123 - 
-124 
erasing 9-91 
establishing 9-32 - 9-41 
formats 9-34 
graphics 9-35 - 9-36 
hardware 9-32 - 9-35 
image (high-res) 9-101 - 
9-102 
overlay (high-res) 
9-107 - 9-108 
protect switch (high- 
res) 9-85 
shell 9-36 
working area (high-res) 
9-76 - 9-77 
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Index 


windows writing 
defining 9-33 - 9-34 a procedure 2-1 - 2-2 
from BASICO9 9-39 - to files 8-3, 11-129 
9-41 
overlay 9-41 XOR command 11-187 - 
predefined 9-32 - 9-33 11-188 
with high-resolution XOR operator 7-7 
9-31 


working area (high-res) 9-76 year 11-27 
workspace 1-3, 3-1 
WRITE command 11-185 - 

11-186 
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Chapter 1 


System Organization 


tn \ OS-9 is composed of a group of modules, each of which has a spe- 
cific function. The following illustration shows the major mod- 
ules. Actual module names are capitalized. 


I/O System Modules 


) 0S-9 KERNEL 
wu (OS9P1, OS9P2) vous 


| Input Output Manager 
(IOMAN) 


Disk File Pipe File 
Manager Manager 
(RBF) (Pipeman) 


Char. File 
Manager Printer $10 
(SCF) 


ACIAPak ModPak CC3I0 
Driver Driver 


20 o 


CC3Disk 
Disk 
Driver 


CC3Hdisk 
Disk 
Driver 


Ram 
Ram Disk 
Driver 


RBF Device Descriptors Pipe Descr. SCF Device Descriptors 
Vdgint GrfInt Windlnt 
CC310 CC310 CC310 
Interface Interface Interface 


=] | le) 
Desc 
a> Term_Win wll wit} w2 
Desc 


OS-9 COMPONENT MODULE ORGANIZATION 
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Color Computer OS-9 Modules 
IOMAN Input/output management 


INIT System initialization table 

CLOCK Software routine time management 
RBF Random block file management 

SCF Sequential character file management 


PIPEMAN Pipe file management 
CC38DISK Color Computer disk driver 
CC3IO Color Computer input/output driver 


The VDGINT (video display generator) provides both interface 
functions and low-level routines for Color Computer 2 VDG 
compatibility. 


The GRFINT interface provides high-level graphics code interpre- 
tation and interface functions. 


The WINDINT interface contains all the functions of GRFINT, 
along with additional support for Multiview functions. If you are 
using Multiview, exclude GRFINT from the system. 


Both WINDINT and GRFINT use the low-level driver GRFDRV 
to perform the actual drawing on bitmap screens. 


Term__VDG uses CC3IO and VDGINT. TERM__WIWN and all 
window descriptors (W, W1, W2, and so on) use CC3I0O, WIN- 
DINT, GRFINT, and GRFDRV modules. 


Kernel, Clock Module, and INIT 


The system’s first level contains the kernel, clock module, and 
INIT. 


The kernel provides basic system services, such as multitasking 
and memory management. It links all other OS-9 modules into 
the system. 


The clock module is a software handler for the real-time clock 
hardware. 


INIT is an initialization table used by the kernel during system 
startup. This table loads initial tasks and specifies initial table 
sizes and initial system device names. It is loaded into RAM 
(random access memory) by the OS-9 bootstrap module Boot. 
Boot also loads the OS9P2 and INIT modules during system 
startup. 
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There are two ways to run boot: 


e Using the DOS command with Color Disk BASIC, Ver- 
sion 1.1, or later. 


@ Pressing the reset button after OS-9 is running. 


Input/Output Modules 


The remaining modules make up the OS-9 I/O system. They are 
defined briefly here and are discussed in detail in Chapter 4. 


I/O Manager 


The system’s second level (the level below the kernel) contains 
the input/output manager, IOMAN. The I/O manager provides 
common processing for all input/output operations. It is required 
for performing any input/output supported by OS-9. 


File Managers 


The system’s third level contains the file managers. File man- 
agers perform I/O request processing for similar classes of I/O 
devices. There are three file managers: 


RBF manager The random block file manager processes 
all disk I/O operations. 


SCF manager The sequential character file manager han- 
dles all non-disk I/O operations that operate 
one character at a time. These operations 
include terminal and printer I/O. 


PIPEMAN The pipe file manager handles pipes. Pipes 
are memory buffers that act as files. Pipes 
are used for data transfers between 
processes. 


Device Drivers 


The system’s fourth level contains the device drivers. Device 
drivers handle basic I/O functions for specific I/O controller hard- 
ware. You can use pre-written drivers, or you can write your 
own. 
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Device Descriptors 


The system’s fifth level contains the device descriptors. Device 
descriptors are small tables that define the logical name, device 
driver, and file manager for each I/O port. They also contain port 
initialization and port address information. Device descriptors 
require only one copy of each I/O controller driver used. 


Shell 


The shell is the command interpreter. It is a program and not a 
part of the operating system. The shell is fully described in the 
OS-9 Commands manual. 


1-4 


Chapter 2 


The Kernel 


The kernel is the core of OS-9. The kernel supervises the system 
and manages system resources. Half of the kernel (called 
OS9P1) resides in the boot module. The other half of the kernel 
(called OS9P2) is loaded into RAM with the other OS-9 modules. 


The kernel’s main functions are: 
® System initialization after reset 
@ Service request processing 
@ Memory management 
® Multiprogramming management 
e Interrupt processing 


I/O functions are not included in the list because the kernel does 
not directly process them. Instead, it passes I/O system calls to 
the I/O Manager for processing. 


System Initialization 


After a hardware reset, the kernel initializes the system. This 
involves: 


1. Locating modules loaded in memory from the OS-9 Boot file. 
2. Determining the amount of available RAM. 


3. Loading any required modules that were not loaded from the 
OS-9 Boot file. 


OS-9 Level Two cannot install new system calls using the OS-9 
Level One system call F$SSvc. F$SSve does not work with a 
Level Two user program because of the separation of system and 
user address space. 
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OS9P3 can be used to tailor the system to fit specific needs. The 
following listing is an example of how to use the OS9P3 module. 


Microware 0S-9 Assembler 2.1 11/18/83 16:06:01 Page 004 


0S-9 Level TWO V1.2, part 2 - 0S-9 System Symbol Definitions 


00001 
00002 
00003 


O00 11 ARGUE GGG HARRAH RARER EERE EEE 


O0012 + 

00013 * Module Header 

00014 + 

00015 O0Ct Type set Systm+Objct 

00016 0081 Revs set Retnt+t 

00017 0000  87CDOOSE mod OS9End,OS9Name, Type Revs, Cold, cab 
00018 00D 4F533970  OS9Name fecs "“Q59p3" 

00019 

00029 @0i2 Of feb {1 edition number 

0030 use defsfile 

00031 0002 level equ 2 

00032 opt -c 

9033 opt f 

00041 

0042 I II AR RRR EER RRR A RHE 
00043 + 

00044 + Routine Cold 

00045 + 

00040 + 

00047 

00048 0013 318D0004 Cold leay SveTbl,per get service routine 
00049 0017 103F32 059 F$SSvc «install new service 
00050 O01A 39 rts 

00051 

0052 

00053 UAT RARER ARE EHH HE 
00054 «+ 

0005S = + Service Routines Initialization Table 
00056 +* 

00057 

0058 02s FSSAYHI equ $25 set up new call 

00059 + Add this to the user os9defs file, 

0060 


aan eee eee errr eer 
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00061 018 SvcTbl equ # 

00062 O01B 25 fob = FSSAYHI 
om $0063 O01C 0001 fdb SayHi-#-2 
| / 00064 QO1E 89 fob = $80 


Microware 05-9 Assembler 2.1 11/18/83 16:06:01 Page O02 
05-9 Level TWO V1.2, part 2 - 05-9 system Symbol Definitions 


10068 * 

00069 Service call Say Hello to user 

00070 * 

00071 Input: U = Registers ptr 

00072 ¢ R$X,u = Message ptr (if @ send default) 
00073 # Max message length = 40 bytes, 

00074 * 

00075 *Dutput: Message sent to standard error path of user. 
00076 ¢ 

0077 tData:  D.Proc 


0078 # 
c» 0079 
00080 O01F  AE44 sayHi ldx RSX ,u gel mess. address 
00081 9021 2619 bne sayHi6 bra if not default 


$0082 0023 109659 ldy D.Proc get proc descr ptr 
00083 0026 EE24 ldu PSSP,,y get caller's stack 
00084 0028  33C8D8 leau = -4u room for message 
00085 0028 96Da lda D.Systsk  system’s task num 
$0086 02D £626 ldb PSTASK,y caller's task num 
00087 O02F 10860028 ldy #49 set byte count 
00088 0033 308D0012 leax Hello,per destination ptr 
00089 0037 103F38 059 F§Move mess into user mem 
00090 003A 3004 leax Qu 
00091 G03C 10860028  SayHié ldy #49 get max byte count 
00092 0040 DESa ldu D.Proc get proc desc ptr 
00093 0042 A6C832 lda PSPATH+2,u path num of stderr 
00094 0045 103F8C 059 I$WritLn write mess line 
00095 0048 39 rts 
00096 

Cc 00097 0049 48656C6C Hello fee "Hello there user," 
00098 OSA aD fcb $)) 
0099 
00100 058 510486 emod module CRC 
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00102 OO5E 059End equ t 
00103 
00104 end 


$0000 error(s) 

00000 warning(s) 

$005E 00094 program bytes generated 
$0000 00000 data bytes allocated 
$2884 10372 bytes used for symbols 


System Call Processing 


System calls are used to communicate between OS-9 and assem- 
bly-language programs for such functions as memory allocation 
and process creation. In addition to I/O and memory manage- 
ment functions, system calls have other functions. These include 
interprocess control and timekeeping. 


System calls use the SWI2 instruction followed by a constant 
byte representing the code. You usually pass parameters for sys- 
tem calls in the 6809 registers. 


OS9Defs and Symbolic Names 


A system-wide assembly-language equate file, called OS9Defs, 
defines symbolic names for all system calls. This file is included 
when assembling hand-written or compiler-generated code. The 
OS-9 assembler has a built-in macro to generate system calls. 
For example: 


O0S9 I$Read 
is recognized and assembled as equivalent to: 


SWI2 
FCB I$¢Read 


The OS-9 assembly macro OS9 generates an SWI2 function. The 
label I$Read is the label for the code $89. 


Types of System Calls 


System calls are divided into two categories, I/O calls and func- 
tion calls. 
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I/O calls perform various input/output functions. The kernel 
passes calls of this type to the I/O manager for processing. The 
symbolic names for I/O calls begin with I$. For example, the 
Read system call is called I$Read. 


Function calls perform memory management, multi-program- 
ming, and other functions. Most are processed by the kernel. The 
symbolic names for function calls begin with F$. For example, 
the Link function call is called F$Link. 


The function calls include user calls and privileged system mode 
calls. (See Chapter 8, “System Calls”, for more information.) 


Memory Management 


Memory management is an important operating system function. 
Using memory modules, OS-9 manages the logical contents of 
memory and the physical assignment of memory to programs. 


All programs that are loaded must be in the memory module for- 
mat. This format allows OS-9 to maintain a module directory of 
all the programs in memory. The directory contains information 
about each module, including its name and address and the 
number of processes using it. The number of processes using a 
module is called the module’s link count. 


When a module’s link count is zero, OS-9 deallocates its part of 
memory and removes its name from the module directory. 


Memory modules are the foundation of OS-9’s modular software 
environment. Advantages of memory management are: 


@ Automatic runtime linking of programs to libraries of 
utility modules 

@ Automatic sharing of re-entrant programs 

@ Replacement of small sections of large programs into 
memory for update or correction 


Memory Use 


OS-9 reserves some space at the top and bottom of RAM for its 
own use. The amount depends on the sizes of system tables that 
are specified in the INIT module. 
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OS-9 pools all other RAM into a free memory space. As the sys- 
tem allocates or deallocates memory, it dynamically takes it 
from or returns it to this pool. RAM does not need to be contig- 
uous because the memory management unit can dynamically 
rearrange memory addresses. 


The basic unit of memory allocation is the 256-byte page. OS-9 
always allocates memory in whole numbers of pages. 


The data structure that OS-9 Level Two uses to keep track of 
memory allocation is a 256-byte bit map. Each bit in this table 
is associated with a specific page of memory. A cleared bit indi- 
cates that the page is free and available for assignment. A set 
bit indicates that the page is in use (that no RAM is free at that 
address). OS-9 Level Two always allocates memory in 8192-byte 
increments. This is the smallest memory block that the memory 
management hardware supports. 


OS-9 automatically allocates memory when any of the following 
occurs: 


@ Program modules are loaded into RAM 
e Processes are created 


@ Processes execute system calls to request additional 
RAM 


@ OS-9 needs I/O buffers or larger tables 


OS-9 also has inverse functions to deallocate memory allocated 
to program modules, new processes, buffers, and tables. 


In general, memory for program modules and buffers is allocated 
from high addresses downward. Memory for process data areas is 
allocated from low addresses upward. 


Following, is a memory map of a typical system. Actual memory 
sizes and addresses can vary depending on the exact system 
configuration. 
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Color Computer OS-9 Typical Memory Map 


+ $7FFFF 
I/O Device Addresses 
+ $7FFO0O0 
Reserved I/O Devices 
+ $7FE80 
Reserved Common Memory 
+ $7FEO00 
OS-9 Kernel 
+ varies 
Bottom of Memory 
in a 128K System 
+ $60000 
Bottom of Memory 
in a 512K System 
+ $00000 


Figure 2.1 


Note: The high two pages of every logical address space 
contain the defined areas I/O Device Addresses, Reserved 
I/O Devices, and Reserved Common Memory. 


Memory Management Hardware 


The 8-bit CPU in the Color Computer 3 can directly address only 
64 kilobytes of memory using its 16 address lines (A0-A15). The 
Color Computer 3’s Memory Management Unit (MMU) extends 
the addressing capability of the computer by increasing the 
address lines to 19 (A0-A18). This lets the computer address up 
to 512 kilobytes of memory ($0-$7F FFF). 


The 512K address space is called the physical address space. The 
physical address space is subdivided into 8K blocks. The six high 
order address bits (A13-A18) define a block number. 
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OS-9 creates a logical address space of up to 64K for each task 
by using the FORK system call. Even though the memory 
within a logical address space appears to be contiguous, it might 
not be—the MMU translates the physical addresses to access 
available memory. Address spaces can also contain blocks of 
memory that are common to more than one map. 


The MMU consists of a multiplexer and a 16 by 6-bit RAM 
array. Each of the 6-bit elements in this array is an MMU task 
register. The computer uses these task registers to determine 
the proper 8-kilobyte memory segment to address. 


The MMU task registers are loaded with addressing data by the 
CPU. This data indicates the actual location of each 8-kilobyte 
segment of the current system memory. The task registers are 
divided into two sets consisting of eight registers each. Whether 
the task register select bit (TR bit) is set or reset, determines 
which of the two sets is to be used. 


The relation between the data in the task register and the gen- 
erated addresses is as follows: 


D5 | D4 | D3 | D2 | Dt | Do_ 


a 
Memory Address | Al18 | Al7 | A16 | Al15 |} Al4 | Al13 


Figure 2.2 


When the CPU accesses any memory outside the I/O and control 
range (XFFO0=XFFFF), the CPU address lines (A13-A15) and 
the TR bit determine what segment of memory to address. This 
is done through the multiplexer when SELECT is low. (See the 
following table.) 


When the CPU writes data to the MMU, AO-A3 determine the 
location of the MMU register to receive the incoming data when 
SELECT is high. The following diagram illustrates the operation 
of the Color Computer 3’s memory management: 
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DO0-D5 
CPU data 


A13-A15 
TR bit pb 


A0-A3 


SELECT 


Figure 2.3 
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The system uses the data from the MMU registers to determine 
the block of memory to be accessed, according to the following 


table: 


fen fed a eek ce rococoes|Eg 


A15 Al4 Al3 


0 
0 
0 
0 
1 
i 
1 
1 
0 
0 
0 
0 
1 
i 
i 
i 


PROOF rFROO]/FPHROOHFOO 


RPOrRMOrFRORO]/FPFOrFROrFOFS 


X0000-X1FFF 
X2000-X3FFF 
X4000-X5FFF 
X6000-X7FFF 
X8000-X9FFF 
XA000-XBFFF 
XC000-XDFFF 
XE000-XFFFF 


X0000-X1 FFF 
X2000-X3FFF 
X4000-XSFFF 
X6000-X7FFF 
X8000-X9FFF 
XA000-XBFFF 
XCO000-XDFFF 
XE000-XFFFF 


Figure 2.4 


MMU 
AddressRange Address 
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Range 


From 


00000 
02000 
04000 
06000 
08000 
0A000 
0C000 
OE000 


10000 
12000 
14000 
16000 
18000 
1A000 
1C000 
1000 


20000 
22000 
24000 
26000 
28000 
2A000 
2C000 
2000 


30000 
32000 
34000 
36000 
38000 


To 


O1FFF 
O3FFF 
O5FFF 
O7FFF 
OOF FF 
OBFFF 
ODFFF 
OFFFF 


11FFF 
13FFF 
15FFF 
17FFF 
19FFF 
1BFFF 
1DFFF 
1FFFF 


21FFF 
23FFF 
25FFF 
27FFF 
29FFF 
2BFFF 
2DFFF 
2FFFF 


SIFFF 
S3FFF 
S5FFF 
3T7TFFF 
SOFFF 


3A000 3BFFF 
3C000 3DFFF 


3EK000 
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Block Range 
Number From To 
00 40000 41FFF 
O01 42000 43FFF 
02 44000 45FFF 
03 46000 47FFF 
04 48000 49FFF 
05 4A000 4BFFF 
06 4C000 4DFFF 
07 4E000 4FFFF 
08 50000 51FFF 
09 52000 53FFF 
OA 54000 55FFF 
OB 56000 57FFF 
OC 58000 59FFF 
OD 5A000 5BFFF 
OE 5C000 5DFFF 
OF 5E000 5SFFFF 
10 60000 61FFF 
Lt 62000 63FFF 
12 64000 65FFF 
13 66000 67FFF 
14 68000 69FFF 
1B 6A000 6BFFF 
16 6C000 6DFFF 
Ly 6E000 6FFFF 
18 70000 71FFF 
19 72000 73FFF 
1A 74000 75FFF 
1B 76000 77FFF 
1C 78000 79FFF 
1D 7A000 7BFFF 
1E 7C000 7DFFF 
1F 7E0O00 7FFFF 
Figure 2.5 


The translation of physical address to 8K-blocks is as follows: 


Block 


Number 


20 
21 
22 
23 
24 
25 
26 
27 


28 
29 
2A 
2B 
2C 
2D 
2E 
2F 


30 
31 
32 
33 
34 
30 
36 
37 


38 
39 
3A 
3B 
3C 
3D 
3K 
3F 


ed 
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In order for the MMU to function, the TR bit at $FF90 must be 
cleared and the MMU must be enabled. However, before doing 
this, the address data for each memory segment must be loaded 
into the designated set of task registers. For example, to select a 
standard 64K map in the top range of the Color Computer 3’s 
512K RAM, with the TR bit set to 0, the following values must 
be panel into the MMU’s registers: 


aie Data Data Address 
Address — (Bin) Range 


FFAO 111000 70000-71F FF 
FFA1 111001 72000-73F FF 
111010 74000-75F FF 
111011 76000-77F FF 
111100 78000-79F FF 
LA EEO. 7A000-7BFFF 
LIt110 7C000-7DFFF 
i See el 7K000-7F FFF 


Figure 2.6 


Although this table shows MMU data in the range $38 to 3F, 
any data between $0 and $3F can be loaded into the MMU reg- 
isters to select memory addresses in the range 0 to $7FFFF, as 
illustrated by Figure 2.5. 


Normally, the blocks containing I/O devices are kept in the sys- 
tem map, but not in the user maps. This is appropriate for time- 
sharing applications, but not for process control. To directly 
access I/O devices, use the F$MspBlk system call. This call 
takes a starting block number and block count, and maps them 
into unallocated spaces of the process’s address space. The sys- 
tem call returns the logical address at which the blocks were 
inserted. 


For example, suppose a display screen in your system is allo- 
cated at extended addresses $7A000-$7DFFF (blocks 3D and 
3E). The following system call maps them into your address 
space: 


ldb #2 number of blocks 

Sales #3D starting block number 

059 F$MapBlk call MapBlk 

stu TOPorts Save address where mapped 
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On return, the U register contains the starting address at which 
the blocks were switched. For example, suppose that the call 
returned $4000. To access extended address $7A020, write to 
$4020. 


Other system calls that copy data to or from one task’s map to 
another are available, such as F$STABX and F$Move. Some of 
these calls are system mode privileged. You can unprotect them 
by changing the appropriate bit in the corresponding entry of 
the system service request table and then making a new system 
boot with the patched table. 


Multiprogramming 


OS-9 is a multiprogramming operating system. This means that 
several independent programs called processes can be executed at 
the same time. By issuing the appropriate system call to OS-9, 
each process can have access to any system resource. 


Multiprogramming functions use a hardware real-time clock. 
The clock generates interrupts 60 times per second, or one every 
16.67 milliseconds. These interrupts are called ticks. 


Processes that are not waiting for some event are called active 
processes. OS-9 runs active processes for a specific system- 
assigned period called a time slice. The number of time slices 
per minute during which a process is allowed to execute depends 
on a process’s priority relative to all other active processes. 
Many OS-9 system calls are available to create, terminate, and 
control processes. 


Process Creation 


A process is created when an existing process executes a Fork 
system call (F$Fork). This call’s main argument is the name of 
the program module that the new process is to execute first (the 
primary module). 


Finding the Module. OS-9 first attempts to find the module in 
the module directory. If it does not find the module, OS-9 usu- 
ally attempts to load into memory a mass-storage file in the exe- 
cution directory, with the requested module name as a filename. 
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Assigning a Process Descriptor. Once OS-9 finds the module, 
it assigns the process a data structure called a process descrip- 
tor. This is a 64-byte package that contains information about 
the process, its state (see the following section “Process States”), 
memory allocations, priority, queue pointers, and so on. OS-9 
automatically initializes and maintains the process descriptor. 
The process itself cannot access the descriptor; it has no need to 
do so. 


Allocate RAM. The next step is to allocate RAM for the pro- 
cess. The primary module’s header contains a storage size. OS-9 
uses this size unless the Fork system call requests a larger area. 
OS-9 then attempts to allocate a memory area of the specified 
size from the free memory space. The memory space does not 
need to be contiguous. 


Proceed or Terminate. If OS-9 can perform all of the previous 
steps, it adds the new process to the active process queue for exe- 
cution scheduling. If it cannot, it terminates the creation; the 
process that originated the Fork is informed of the error. 


Assign Process ID and User ID. OS-9 assigns the new process 
a unique number called a process ID. Other processes can com- 
municate with the process by referring to its ID in various sys- 
tem calls. 


The process also has a user ID, which is used to identify all pro- 
cesses and files belonging to a particular user. The user ID is 
inherited from the parent process. 


Process Termination. A process terminates when it executes 
an Exit system call (F$Exit) or when it receives a fatal signal. 
The termination closes any open paths, deallocates memory used 
by the process, and unlinks its primary module. 


Process States 
At any instant a process can be in one of three states: 
@ Active—The process is ready for execution. 


@ Waiting—The process is suspended until a child process 
terminates or until it receives a signal. A child process 
is a process that is started (execution is begun by) 
another process—a parent process. 
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@ Sleeping—The process is suspended for a specific period 
of time or until it receives a signal. 


Each state has its own queue, a linked list of descriptors of pro- 
cesses in that state. To change a process’s state, move its 
descriptor to another queue. 


The Active State. Each active process is given a time slice for 
execution, according to its priority. The scheduler in the kernel 
ensures that all active processes, even those of low priority, get 
some CPU time. 


The Wait State. This state is entered when a process executes a 
Wait system call (F$Wait). The process remains suspended until 
one of its child processes terminates or until it receives a signal. 
(See the “Signals” section later in this chapter.) 


The Sleeping State. This state is entered when a process exe- 
cutes a Sleep system call (F$Sleep), which specifies the number 
of ticks for which the process is to remain suspended. The pro- 
cess remains asleep until the specified time has elapsed or until 
it receives a wakeup signal. 


Execution Scheduling 


The OS-9 scheduler uses an algorithm that ensures that all 
active processes get some execution time. 


All active processes are members of the active process queue, 
which is kept sorted by process age. Age is the number of process 
switches that have occurred since the process’s last time slice. 
When a process is moved to the active process queue from 
another queue, its age is set according to its priority—the higher 
the priority, the higher the age. 


Whenever a new process becomes active, the ages of all other 
active processes increase by one time slice count. When the exe- 
cuting process’s time slice has elapsed, the scheduler selects the 
next process to be executed (the one with the next highest age, 
the first one in the queue). At this time, the ages of all other 
active processes increase by one. Ages never go beyond 255. 


A new active process that was terminated while in the system 
state is an exception. This process is given high priority because 
it is usually executing critical routines that affect shared system 
resources. 
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When there are no active processes, the kernel handles the next 
interrupt and then executes a CWA1 instruction. This procedure 
decreases interrupt latency time (the time it takes the system to 
process an interrupt). 


Signals 


A signal is an asynchronous control mechanism used for inter- 
process communication and control. It behaves like a software 
interrupt. It can cause a process to suspend a program, execute 
a specific routine, and then return to the interrupted program. 


Signals can be sent from one process to another process by the 
Send system call (F$Send). Or, they can be sent from OS-9 ser- 
vice routines to a process. 


A signal can convey status information in the form of a 1-byte 
numeric value. Some signal codes (values) are predefined, but 
you can define most. The signal codes are: 


0 = Kill (terminates the process, is non- 
interceptable) 


i = Wakeup (wakes up a sleeping process) 
2 = Keyboard terminate 
3 = Keyboard interrupt 
4 = Window change 
128-255 = User defined 


When a signal is sent to a process, the signal is saved in the 
process descriptor. If the process is in the sleeping or waiting 
state, it is changed to the active state. When the process gets its 
next time slice, the signal is processed. 


What happens next depends on whether or not the process has 
set up a signal intercept trap (signal service routine) by execut- 
ing an Intercept system call (F$lIcpt). 


If the process has set up a signal intercept trap, the process 
resumes execution at the address given in the Intercept call. The 
signal code passes to this routine. Terminate the routine with 
an RTI instruction to resume normal execution of the process. 
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Note: A wakeup signal activates a sleeping process. It sets 
a flag but ignores the call to branch to the intercept 
routine. 


If it has not set up a signal intercept trap, the process is termi- 
nated immediately. It is also terminated if the signal code is 
zero. If the process is in the system mode, OS-9 defers the termi- 
nation. The process dies upon return to the user state. 


A process can have a signal pending (usually because the pro- 
cess has not been assigned a time slice since receiving the sig- 
nal). If it does, and another process tries to send it another 
signal, the new signal is terminated, and the Send system call 
returns an error. To give the destination process time to process 
the pending signal, the sender needs to execute a Sleep system 
call for a few ticks before trying to send the signal again. 


Interrupt Processing 


Interrupt processing is another important function of the kernel. 
OS-9 sends each hardware interrupt to a specific address. This 
address, in turn, specifies the address of the device service rou- 
tine to be executed. This is called vectoring the interrupt. The 
address that points to the routine is called the vector. It has the 
same name as the interrupt. 


The SWI, SWI2, and SWI38 vectors point to routines that read 
the corresponding pseudo vector from the process’s descriptor 
and dispatch to it. This is why the Set SWI system call 
(F$SSWI) is local to a process; it only changes a pseudo vector in 
the process descriptor. 


Hardware Vector 


Table 
Vector Address 
SWI3 $FFF2 
SWI12 S$FFF4 
FIRQ $FFF6 
IRQ S$FFF8 
SWI SFFFA 
NMI S$FFFC 


RESTART $FFFE 
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FIRQ Interrupt. The system uses the FIRQ interrupt. The 
FIRQ vector is not available to you. The FIRQ vector is reserved 
for future use. Only one FIRQ generating device can be in the 
system at a time. 


Logical Interrupt Polling System 


Because most OS-9 I/O devices use IRQ interrupts, OS-9 
includes a sophisticated polling system. The IRQ polling system 
automatically identifies the source of the interrupt, and then exe- 
cutes its associated user- or system-defined service routine. 


IRQ Interrupt. Most OS-9 I/O devices generate IRQ interrupts. 
The IRQ vector points to the real-time clock and the keyboard 
scanner routines. These routines, in turn, jump to a special IRQ 
polling system that determines the source of the interrupt. The 
polling system is discussed in the next section, “Logical Inter- 
rupt Polling System.” 


NMI Interrupt. The system uses the NMI interrupt. The NMI 
vector, which points to the disk driver interrupt service routine, 
is not available to you. 


The Polling Table. The information required for IRQ polling is 
maintained in a data structure called the IRQ polling table. The 
table has a 9-byte entry for each device that might generate an 
IRQ interrupt. The table size is permanent and is defined by an 
initialization constant in the INIT module. Each entry in the 
polling table is given a number from 0 (lowest priority) to 255 
(highest priority). In this way, the more important devices (those 
that have a higher interrupt frequency) can be polled before the 
less important ones. 


Each entry has six variables: 


Polling Address Points to the status register of the device. 
The register must have a bit or bits that 
indicate if it is the source of an interrupt. 


Flip Byte Selects whether the bits in the device status 
register indicate active when set or active 
when cleared. If a bit in the flip byte is set, 
it indicates that the task is active whenever 
the corresponding bit in the status register 
is clear. 
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Mask Byte Selects one or more interrupt request flag 
bits within the device status register. The 
bits identify the active task or device. 


Service Points to the interrupt service routine for Uo 
Routine Address the device. You supply this address. 


Static Points to the permanent storage area 
Storage Address' required by the device service routine. You 
supply this address. 


Priority Sets the order in which the devices are 
polled (a number from 0 to 255). 


Polling the Entries. When an IRQ interrupt occurs, OS-9 
enters the polling system via the corresponding RAM interrupt 
vector. It starts polling the devices in order of priority. OS-9 
loads the status register address of each entry into Accumulator 
A, using the device address from the table. 


OS-9 performs an exclusive-OR operation using the flip byte, fol- 
lowed by a logical-AND operation using the mask byte. If the 
result is non-zero, OS-9 assumes that the device is the source of | 
the interrupt. w/ 


OS-9 reads the device memory address and service routine 
address from the table, and performs the interrupt service 
routine. 


Note: If you are writing your own device driver, terminate 
the interrupt service routine with an RTS instruction, not 
an RTI instruction. 


Adding Entries to the Table. You can make entries to the IRQ 
(interrupt request) polling table by using the Set IRQ system 
call (F$IRQ). Set IRQ is a privileged system call, OS-9 can exe- 
cute it only in the system mode. OS-9 is in system mode when- 
ever it is running a device driver. 


Note: The code for the interrupt polling system is located 
in the I/O Manager module. The OS9P1 and OS9P2 mod- 
ules contain the physical interrupt processing routines. 


2-18 


“™ 


The Kernel / 2 


Virtual Interrupt Processing 


A virtual IRQ, or VIRQ, is useful with devices in Multi-Pak 
expansion slots. Because of the absence of an IRQ line from the 
Multi-Pak interface, these devices cannot initiate physical inter- 
rupts. VIRQ enables these devices to act as if they were inter- 
rupt driven. Use VIRQ only with device driver and pseudo device 
driver modules. VIRQ is handled in the Clock module, which 
handles the VIRQ polling table and installs the FSVIRQ system 
call. Since the F$VIRQ system call is dependent on clock initial- 
ization, the CC3GO module forces the clock to start. 


The virtual interrupt is set up so that a device can be inter- 
rupted at a given number of clock ticks. The interrupt can occur 
one time, or can be repeated as long as the device is used. 


The F$VIRQ system call installs VIRQ in a table. This call 
requires specification of a 5-byte packet for use in the VIRQ 
table. This packet contains: 


@ Bytes for an actual counter 
@ A reset value for the counter 


e A status byte that indicates whether a virtual interrupt 
has occurred and whether the VIRQ is to be re-installed 
in the table after being issued 


F$VIRQ also specifies an initial tick count for the interrupt. 
The actual call is summarized here and is described in detail in 
Chapter 8. 


Call: OSI F$VIRQ 

Input: (Y) = address of 5-byte packet 
(X) = 0 to delete entry, 1 to install entry 
(D) = initial count value 


Output: none 
(CC) carry set on error 
(IS) appropriate error code 


The 5-byte packet is defined as follows: 


Name Offset Function 

Vi,Cnt $0 Actual counter 

Vi.Rst $2 Reset value for counter 
Vi.Stat $4 Status byte 
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Two of the bits in the status byte are used. These are: 


Bit O - set if VIRQ occurs 
Bit 7 - set if a count reset is required 


When making an F$VIRQ call, the packet might require initial- 
ization with a reset value. Bit 7 of the status byte must be 
either set or cleared to signify a reset of the counter or a one- 
time VIRQ call. The reset value does not need to be the same as 
the initial counter value. When OS-9 processes the call, it writes 
the packet address into the VIRQ table. 


At each clock tick, OS-9 scans the VIRQ table and subtracts one 
from each timer value. When a timer count reaches zero, OS-9 
performs the following actions: 


1. Sets Bit 0 in the status byte. This specifies a Virtual IRQ. 
2. Checks Bit 7 of the status byte for a count reset request. 


3. If bit 7 is set, resets the count using the reset value. If bit 7 
is reset, deletes the packet address from the VIRQ table. 


When a counter reaches zero and makes a virtual interrupt 
request, OS-9 runs the standard interrupt polling routine and 
services the interrupt. Because of this, you must install entries 
on both the VIRQ and DIRQ polling tables whenever you are 
using a VIRQ. 


Unless the device has an actual physical interrupt, install the 
device on the IRQ polling table via the F$IRQ system call before 
placing it on the VIRQ table. 


If the device has a physical interrupt, use the interrupt’s hard- 
ware register address as the polling address for the F$IRQ call. 
After setting the polling address, set the flip and mask bytes for 
the device, and make the F$IRQ call. 


If the device is totally VIRQ-driven, and has no interrupts, use 
the status byte from the VIRQ packet as the status byte. Use a 
mask byte of %00000001, defined as Vi.IFlag in the defs file. 
Use a flip byte value of 0. The following examples show how to 
set up both types of VIRQ calls. The first example is taken from 
an ACIA-type driver that has a physical interrupt found in a 
status register, but that cannot be accessed by the processor if 
used in the Multi-Pak. The second example is for a device with 
no physical interrupt handling, all interrupts are handled 
through the VIRQ. 
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* VIRG Example #1 - Device Driver possessing real [RQ’s 


Copyright 1985, 1986 by Microware Systems 
* Corporation. Reproduced Under License 


use defsfile 


* actual mask byte for hardware interrupt 
IRQReq set 110000000 Interrupt Request 


* offset to the actual hardware status register 
Status equ | 


* VIRQ countdown value 
VIRQCNT equ | do the VIRQ on every tick 


KEEKKEHKEEEEKRHEEHREESE 
* Static storage offsets 


* 


org V.oCF room for scf variables 


VIRQBUF rmb 5 buffer for fake interrupt from clock 


MEM equ. Total static storage requirement 


HHEKKEHREHEEEEERES 

* Module Header 

mod MEND,NAM,DRIVR+OBJCT,REENT+1 ,ENT,MEM 
feb UPDAT. 


fob Edition Current Revision 
EEEEKEEERERREREREEEEEEEESE 
* Driver entry jump table 
ENT lbra INIT 

bra READ 

lbra WRITE 

lbra GETSTA 
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bra PUTSTA 
bra TRMNAT 


* Actual mask information for F$IRQ call for the 
* hardware interrupt MASK fcb @ no flip bits 

* fcb IRQReg Irq polling mask 

* fob 1@ (higher) priority 


KEEKKHEKEKEEHRHEESE 

+ [nit 

+ Initialize the device 

* Includes setting up the IR@ and VIRQ entries 


* 


INIT 


* Install IRQ polling Table Entry first 
* Use the hardware status register and the hardware 
* mask 

Idd V.PORT,U get port address in D 

add #Status point to hardware status byte 

leax MASK,PCR get the hardware interrupt mask 

leay MIRQ,PCR address of interrupt service routine 
0S9 FS$IRQ Add to IRQ polling table 

bes INIT9 error - return it 


* Install VIRQ in Clock Module second 
* 

leay VIRQBUF,U get the 5 byte VIRQ buffer pointer 

Ida #$80 get reset flag for repeated VIRQ’s 

sta Vi.Stat,y put it into buffer 

Idd #VIRQCNT get count for number of ticks for the VIRQ 
std Vi.Rst,y put in initial reset value 

Idx #1 put onto table 

os9 FSVIRG make the service request 

bes INIT9 Error - return it 


INITS rts 


READ 
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WRITE 


Mm GETSTA 
PUTSTA 


HEEKKHEHEEEEEHES 


* Subroutine TRMNAT 


Terminate device, including removal from tables 
% 


TRMNAT 


* remove from VIRQ table first 

ldx #2 remove from VIRG table 

leay VIRQBUF ,U get address 

059 FSVIRQ remove modem from VIRQ table 
* next remove from IRQ table 

Idx #9 

ma O59 FSIRQ remove modem from polling tbl 

rts 


RHEE KKHEHHEEEEHEHHER ES 


+ MIRQ 


* process Interrupt 
¥ 


MDIRG 


« actual interrupt service routine > 


rts 


emod Module Cre 
MEND equ * 


a 


* VIRG Example #2 - Device Driver without hardware interrupts 
HRHEEKEHRERERERES 


* STATIC STORAGE DEFINITION 


* 
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VIRQGBF rmb S buffer for VIRQ 
DMEM equ . 


HREEHREKHREKERHREREERE 

* Module Header 

% 

mod DEND,DNAM,DRIVR+OBUCT,REENT+REV, DENT , DMEM 
fob UPDAT. mode byte 


fob 3 EDITION BYTE 


* Driver entry table 

DENT lbra INIT initialize 
lbra READ 
lbra WRITE 
lbra GETSTAT get status 
lbra SETSTAT set status 
lbra TERM terminate 


* Mask information packet for FSIRQ call 
* NOTE: uses the virtual interrupt flag, Vi.IFlag, for 
* the maskbyte 
* 
DMSK fcb @ no flip bits 
feb Vi. IFlag polling mask for VIRQ 
fob 18 priority 


HHEHRHKKHEEEEEEEEEE 


* INITIALIZE STORAGE AND CONTROLLER 
* Includes setting up the IRQ and VIRQ table entries 


* 


INIT 


* set up IRQ table entry first 

* NOTE: uses the status register of the VIRQ buffer for 
* the interrupt status register since no hardware status 
* register is available 


leay VIRQBF+Vi.Stat,U get address of status byte 


a aaaaaaaaaaaaacacaaacacaaaaaaasaaaaaaaaaa 
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ifr y,d put it into D reg 

leay DIRG,PCR get address of interrupt routine 
leax DMSK,PCR get VIRQ mask info 

059 F$IRQ install onto table 

bes INIT9 exit on error 


* now set up the VIRQ table entry 

leay VIRQBF,U point to the S-byte packet 

Ida #$80 get the reset flag to repeat VIRQ’s 

sta Vi.Stat,y save it in the buffer 

Idd #VIRQCNT get the VIR@ counter value 

std Vi.Rst,y save it in the reset area of buffer 
Idx #1 code to install the VIRQ 

059 FS$VIRQ install on the table 

bes INIT9 exit on error 


INIT rts 


READ 
WRITE 
GETSTAT 
PUTSTAT 


RHEE RRRHEREERHREEEE 

* TERM - terminate the device and remove entries from 
* tables 

TERM 


* remove from VIRQ table first 
Idx #0 get zero to remove from table 
leay VIRQBF,U get address of packet 
059 FSVIRQ 
* then remove from IRQ table 
Idx #@ get zero to remove from table 
os9 FSIRGQ 


rts 


KREREREEREEEEEREEEREREREREREERRRERERRRRREEER ERR EEERE REESE 
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* DIRQ - interrupt service routine 


* NOTE: The service routine must be sure to reset the 
* status byte of the VIRQ packet so that the interrupt 


* looks as if it is cleared. 
¥ 


DIRQ 


Ida VIRGBF+Vi.Stat,U get status byte 
anda #$FF-Vi.IFlag mask off interrupt bit 
sta VIRQBF+Vi.Stat,U put it back 


rts 


EMOD 
DEND equ # 


END 
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Memory Modules 


In Chapter 2, you learned that OS-9 is based on the concept that 
memory is modular. This means that each program is considered 
to be an individually named object. 


You also learned that each program loaded into memory must be 
in the module format. This format lets OS-9 manage the logical 
contents of memory, as well as the physical contents. Module 
types and formats are discussed in detail in this chapter. 


Module Types 


There are several types of modules. Each has a different use and 
function. These are the main requirements of a module: 


® It cannot modify itself. 


e It must be position-independent so that OS-9 can load or 
relocate it wherever space is available. In this respect, 
the module format is the OS-9 equivalent of load records 
used in older operating systems. 


A module need not be a complete program or even 6809 machine 
language. It can contain BASICO09 I-code, constants, single sub- 
routines, and subroutine packages. 


Module Format 


Each module has three parts: a module header, a module body, 
and a cyclic-redundancy-check value (CRC value). 
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Module Header 


Program 
or 
Constants 


CRC Value 


Figure 3.1 


Module Header 


At the beginning of the module (the lowest address) is the mod- 
ule header. Its form depends upon the module’s use. 


The header contains information about the module and its use. 
This information includes the following: 


@ Size 

@ Type (machine code, BASICO9 compiled code, and so on) 
e Attributes (executable, re-entrant, and so on) 

e Data storage memory requirements 

e Execution starting address 


Usually, you do not need to write routines to generate the mod- 
ules and headers. All OS-9 programming languages automati- 
cally create modules and headers. 


Module Body 


The module body contains the program or constants. It usually 
is pure code. The module name string is included in this area. 
Figure 3.2 provides the offset values for calculating the location 
of a module’s name. (See “Offset to Module Name”) 


CRC Value 


The last three bytes of the module are the Cyclic Redundancy 
Check (CRC) value. The CRC value is used to verify the integ- 
rity of a module. 
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When the system first loads the module into memory, it per- 
forms a 25-bit CRC over the entire module, from the first byte of 
the module header to the byte immediately before the CRC. The 
CRC polynomial used is $800FE3. 


As with the header, you usually don’t need to write routines to 
generate the CRC value. Most OS-9 programs do this 
automatically. 


Module Headers: Standard Information 


The first nine bytes of all module headers are defined as follows: 


Relative 
Address Use 
$00,$01 Sync bytes ($87,$CD) 
$02,$03 Module size 
$04,$05 Offset to module name 
$06 Module type/Language 
$07 Attributes/Revision level 
$08 Header check 

Figure 3.2 

Sync Bytes 


The sync bytes specify the location of the module. (The first sync 
byte is the start of the module.) These two bytes are constant. 


Module Size 


The module size specifies the size of the module in bytes 
(includes CRC). 


Offset to Module Name 


The offset to module name specifies the address of the module 
name string relative to the start of the module. The name string 
can be located anywhere in the module. It consists of a string of 
ASCII characters with the most significant bit set on the last 
character. 
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Type/Language Byte 


The type/language byte specifies the type and language of the 
module. 


The four most significant bits of this byte indicate the type. 
Eight types are pre-defined. Some of these are for OS-9’s inter- 
nal use only. The type codes are given here (0 is not a legal type 
code): 


Code Module Type sNasme 
$1x Program module Prgrm 
$2x Subroutine module Sbrtn 
$3x Multi-module (for future use) Multi 
$4x Data module Data 
$5x-$Bx User-definable module 
$Cx OS-9 system module Systm 
$Dx OS-9 file manager module FlMgr 
$Ex OS-9 device driver module Drivr 
$F*x OS-9 device descriptor module Devic 
Figure 3.3 


The four least significant bits of Byte 6 indicate the language 
(denoted by x in the previous Figure). The language codes are 
given here: 


Code Language 

$x0 Data (non-executable) 

$x1 6809 object code 

$x2 BASICO09 I-code 

$x3 PASCAL P-code 

$x4-$xF Reserved for future use 
Figure 3.4 


By checking the language type, high-level language runtime 
systems can verify that a module is the correct type before 
attempting execution. BASIC09, for example, can run either I- 
code or 6809 machine language procedures arbitrarily by check- 
ing the language type code. 


Attributes/Revision Level Byte 


The attributes/revision level byte defines the attributes and revi- 
sion level of the module. 
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The four most significant bits of this byte are reserved for mod- 
ule attributes. Currently, only Bit 7 is defined. When set, it indi- 
cates the module is re-entrant and, therefore, shareable. 


The four least significant bits of this byte are a revision level in 
the range 0 to 15. If two or more modules have the same name, 
type, language, and so on, OS-9 keeps in the module directory 
only the module having the highest revision level. Therefore, you 
can replace or patch a ROM module, simply by loading a new, 
equivalent module that has a higher revision level. 


Note: A previously linked module cannot be replaced until 
its link count goes to zero. 


Header Check 


The header check byte contains the one’s complement of the 
Exclusive-OR of the previous eight bytes. 


Module Headers: Type-Dependent 
Information 


More information usually follows the first nine bytes of a module 
header. The layout and meaning vary, depending on the module 


type. 
Module types $Cx-$Fx (system module, file manager module, 


device driver module, and device descriptor module) are used 
only by OS-9. Their formats are given later in the manual. 


Module types $1x through $Bx have a general-purpose executa- 
ble format. This format is often used in programs called by 
F$Fork or F$Chain. Here is the format used by these module 


types: 
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Executable Memory Module Format 


Relative Check 
Address Use Range we 


$00 

Sync Bytes ($87,$CD) 
$01 
$02 

Module Size (bytes) 
$03 
$04 

Module Name Offset header 
$05 parity 


$08 Header Parity Check CRC 
ww 
$09 
Execution Offset 
$0A 
$0B 
Permanent Storage Size 
$0C 
$0D (Additional optional header 
extensions) 
Module Body 
object code, constants, 
and so on 
CRC Check Value , 


Figure 3.5 


LO 
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As you can see from the preceding chart, the executable memory 
has four extra bytes in its header. They are: 


$09, $0A Execution offset 
$0B,$0C Permanent storage size 


Execution Offset. The program or subroutine’s offset starting 
address, relative to the first byte of the sync code. A module that 
has multiple entry points (such as cold start and warm start) 
might have a branch table starting at this address. 


Permanent Storage Size. The minimum number of bytes of 
data storage required to run. Fork and Chain use this number 
to allocate a process’s data area. 


If the module is not directly executed by a Fork or Chain system 
call (for instance a subroutine package), this entry is not used by 
OS-9. It is commonly used to specify the maximum stack size 
required by re-entrant subroutine modules. The calling program 
can check this value to determine if the subroutine has enough 
stack space. 


When OS-9 starts after a single system reset, it searches the 
entire memory space for ROM modules. It finds them by looking 
for the module header sync code ($87,$CD). 


When OS-9 detects the header sync code, it checks to see if the 
header is correct. If it is, the system obtains the module size 
from the header and performs a 24-bit CRC over the entire mod- 
ule. If the CRC matches, OS-9 considers the module to be valid 
and enters it into the module directory. All ROM modules that 
are present in the system at startup are automatically included 
in the system module directory. 


After the module search, OS-9 links to the component modules it 
found. This is the secret to OS-9’s ability to adapt to almost any 
6809 computer. It automatically locates its required and optional 
component modules and rebuilds the system each time it is 
started. 
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Chapter 4 


OS-9’s Unified 
Input/Output System 


Chapter 1 mentioned that OS-9 has a unified I/O system, con- 
sisting of all modules except those on the kernel level. This chap- 
ter discusses the I/O modules in detail. 


I/O System Modules 
: Serene, 


Input/Output Manager 
(OMAN) 


Disk File 
Manager 
(RBF) 


Pipe File 
Manager 
(Pipeman) 


Char. File 
Manager Printer $10 
(SCF) 


ACIAPak ModPak CC3I0 
Driver Driver 
Driver Driver 


[off e][|[oe][e][_ ree] [of 


RBF Device Descriptors Pipe Descr. SCF Device Descriptors 


CC3Disk 
Disk 


CC3Hdisk 
Disk 


Ram 
Ram Disk 
Driver 


VdgInt Grflnt Windlnt 


CC310 CC310 CC3I0 
Interface Interface Interface 


Term_Vdg 
Desc 
Eee 
Desc 


OS-9 COMPONENT MODULE ORGANIZATION 
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The VDG Interface performs both interface and low level routines 
for VDG Color Computer 2 compatible modes and has limited 
support for high res screen allocation. 


The GrfInt Interface provides the standard code interpretations 
and interface functions. 


The WindInt Interface, available in the Multi-view package, con- 
tains all the functionality of GrfInt, along with additional sup- 
port features. If you use WindInt, do not include GrfInt. 


Both WindInt and GrfInt use the low-level driver GrfDrv to per- 
form drawing on the bit-map screens. 


Term__VDG uses CC3IO/VdgInt while Term—win and all win- 
dow descriptors use CC3IO/(WindInt/GrfInt)/GrfDrv modules. 


The I/O system provides system-wide, hardware-independent I/O 
services for user programs and OS-9 itself. All I/O system calls 
are received by the kernel and passed to the I/O manager for 
processing. 


The I/O manager performs some processing, such as the alloca- 
tion of data structures for the I/O path. Then, it calls the file 
managers and device drivers to do most of the work. Additional 
file manager, device driver, and device descriptor modules can be 
loaded into memory from files and used while the system is 
running. 


The I/O Manager 


The I/O manager provides the first level of service of I/O system 
calls. It routes data on I/O process paths to and from the appro- 
priate file managers and device drivers. 


The I/O Manager also maintains two important internal OS-9 
data structures—the device table and the path table. Never mod- 
ify the I/O manager. 


When a path is opened, the I/O manager tries to link to a mem- 
ory module that has the device name given or implied in the 
pathlist. This module is the device descriptor. It contains the 
names of the device driver and file manager for the device. The 
I/O manager saves the names so later system calls can be routed 
to these modules. 
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File Managers 


OS-9 can have any number of file manager modules. Each of 
these modules processes the raw data stream to or from a class 
of device drivers that have similar operational characteristics. It 
removes aS many unique characteristics as possible from I/O 
operations. Thus, it assures that similar devices conform to the 
OS-9 standard I/O and file structure. 


The file manager also is responsible for mass storage allocation 
and directory processing, if these are applicable to the class of 
devices it serves. 


File managers usually buffer the data stream and issue requests 
to the kernel for dynamic allocation of buffer memory. They can 
also monitor and process the data stream, for example, adding 
line-feed characters after carriage-return characters. 


The file managers are re-entrant. The three standard OS-9 file 
managers are: 


@ Random block file manager: The RBF manager supports 
random-access, block-structured devices such as disk sys- 
tems and bubble memories. (Chapter 5 discusses the 
RBF manager in detail.) 


® Sequential Character File Manager: The SCF manager 
supports single-character-oriented devices, such as CRTs 
or hardcopy terminals, printers, and modems. (Chapter 6 
discusses SCF in detail.) 


@ Pipe File Manager (PIPEMAN): The pipe manager sup- 
ports interprocess communication via pipes. 


File Manager Structure 


Every file manager must have a branch table in exactly the fol- 
lowing format. Routines that are not used by the file manager 
must branch to an error routine, that sets the carry and loads 
Register B with an appropriate error code before returning. Rou- 
tines returning without error must ensure that the carry bit is 
clear. 
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* All routines are entered with: 
* CY) = Path Descriptor pointer 
* CU) = Caller’s register stack pointer 


Enteyrt sequ. * 
lbra Create 
lbra Open 
lbra MakDir 
lbra ChgDir 
lbra Delete 
lbra Seek 
lbra Read 
lbra Write 
lbra ReadLn 
lbra WriteLn 
lbra GetStat 
lbra PutStat 
lbra Close 


Create, Open 


Create and Open handle file creating and opening for devices. 
Typically, the process involves allocating any required buffers, 
initializing path descriptor variables, and establishing the path 
name. If the file manager controls multi-file devices (RBF), 
directory searching is performed to find or create the specified 
file. 


Makdir 


Makdir creates a directory file on multi-file devices. Makdir is 
neither preceded by a Create nor followed by a Close. File man- 
agers that are incapable of supporting directories need to return 
carry set with an appropriate error code in Register B. 


ChgDir 


On multi-file devices, ChgDir searches for a directory file. If 
ChgDir finds the directory, it saves the address of the directory 
(up to four bytes) in the caller’s process descriptor. The descrip- 
tor is located at P$DIO+2 (for a data directory) or P$DIO+8 
(for an execution directory). 


ww 
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In the case of the RBF manager, the address of the directory’s 
file descriptor is saved. Open/Create begins searching in the cur- 
rent directory when the caller’s pathlist does not begin with a 
slash (/). File managers that do not support directories should 
return the carry set and an appropriate error code in Register 
B. 


Delete 


Multi-file device managers handle file delete requests by initiat- 
ing a directory search that is similar to Open. Once a device 
manager finds the file, it removes the file from the directory. 
Any media in use by the file are returned to unused status. In 
the case of the RBF manager, space is returned for system use 
and is marked as available in the free cluster bit map on the 
disk. File managers that do not support multi- file devices 
return an error. 


Seek 


File managers that support random access devices use Seek to 
position file pointers of an already open path to the byte speci- 
fied. Typically, the positioning is a logical movement. No error is 
produced at the time of the seek if the position is beyond the 
current “end of file”. 


Normally, file managers that do not support random access 
ignore Seek. However, an SCF-type manager can use Seek to 
perform cursor positioning. 


Read 


Read returns the number of bytes requested to the user’s data 
buffer. Make sure Read returns an EOF error if there is no data 
available. Read must be capable of copying pure binary data, and 
generally performs no editing on the data. Generally, the file 
manager calls the device driver to actually read the data into 
the buffer. Then, the file manager copies the data from the buffer 
into the user’s data area to keep file managers device- 
independent. 
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Write 


The Write request, like Read, must be capable of recording pure 
binary data without alteration. The routines for Read and Write 
are almost identical with the exception that Write uses the 
device driver’s output routine instead of the input routine. The 
RBF manager and similar random access devices that use fixed- 
length records (sectors) must often preread a sector before writ- 
ing it, unless they are writing the entire sector. In OS-9, writing 
past the end of file on a device expands the file with new data. 


ReadLn 


ReadLn differs from Read in two respects. First, ReadLn termi- 
nates when the first end-of-line (carriage return) is encountered. 
ReadLn performs any input editing that is appropriate for the 
device. In the case of SCF, editing involves handling functions 
such as backspace, line deletion, and the removal of the high- 
order bit from characters. 


WriteLn 


WriteLn is the counterpart of ReadLn. It calls the device driver 
to transfer data up to and including the first (if any) carriage 
return encountered. Appropriate output editing can also be per- 
formed. For example, SCF outputs a line feed, a carriage return 
character, and nulls (if appropriate for the device). It also pauses 
at the end of a screen page. 


GetStat, PutStat 


The GetStat (get status) and PutStat (put status) system calls 
are wildcard calls designed to provide a method of accessing fea- 
tures of a device (or file manager) that are not generally device 
independent. The file manager can perform specific functions 
such as setting the size of a file to a given value. Pass unknown 
status calls to the driver to provide further means of device inde- 
pendence. For example, a PutStat call to format a disk track 
might behave differently on different types of disk controllers. 
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Close 


Close is responsible for ensuring that any output to a device is 
completed. (If necessary, Close writes out the last buffer.) It 
releases any buffer space allocated in an Open or Create. Close 
does not execute the device driver’s terminate routine, but can 
do specific end-of-file processing if you want it to, such as writ- 
ing end-of-file records on disks, or form feeds on printers. 


Interfacing with Device Drivers 


Strictly speaking, device drivers must conform to the general for- 
mat presented in this manual. The I/O Manager is slightly dif- 
ferent because it only uses the Init and Terminate entry points. 
Other entry points need only be compatible with the file man- 
ager for which the driver is written. For example, the Read entry 
point of an SCF driver is expected to return one byte from the 
device. The Read entry point of an RBF driver, on the other 
hand, expects Read to return an entire sector. 


The following code is part of an SCF file manager. The code 
shows how a file manager might call a driver. 
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KHHEKEKKKHHEKKKHEKEEE 


* I[OEXEC 

* Execute Device’s Read/Write Routine 

* 

+ Passed: CA) = Qutput character Cwrite) 

* CX)? = Device Table entry: pir 

* CY? = Path Déeseripitor. pointer 

* CU) = Offset of routine CD$Read, 


D¢Write)d 
Input char Cread) 
Error code, CC Set af -error 


* Returns: CA) 
* (CB) 
* Destroys B,CC 


IQDEXEC. pshs €4,%.Vs4 save registers 

ldu VSSTATsx get static storage tor driver 
ldx V$DRIV,x get driver module address 

ldd M$EXEC,x and offset of execution entries 
addd 5,5 offset by read/write 

leax d,x absolute entry address 

lda ,5+ restore char Cfor write) 

far 0, % execute driver read/write 

Puls ek Y5Uspe return CAd=cnar, K<B2erpor 


emod Module CRC 
Size @€0u * Size of sequential Tile manager 


Device Driver Modules 


The device driver modules are subroutine packages that perform 
basic, low-level I/O transfers to or from a specific type of I/O 
device hardware controller. These modules are re-entrant. So, 
one copy of the module can concurrently run several devices that 
use identical I/O controllers. 


Device driver modules use a standard module header, in which 
the module type is specified as code $Ex (device driver). The exe- 
cution offset address in the module header points to a branch 
table that has a minimum of six 3-byte entries. 


Each entry is typically an LBRA to the corresponding subrou- 
tine. The file managers call specific routines in the device driver 
through this table, passing a pointer to a path descriptor and 
passing the hardware control register address in the 6809 regis- 
ters. The branch table looks like this: 


wo 


Code 


+ $00 
+ $03 
+ $06 
+ $09 
+ $0C 
+ $0F 


OS-9’s Unified Input/Output System / 4 


Meaning 


Device initialization routine 
Read from device 

Write to device 

Get device status 

Set device status 

Device termination routine 


(For a complete description of the parameters passed to these 
subroutines, see the “Device Driver Subroutines” sections in 
Chapters 5 and 6.) 
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Device Driver Module Format 


Relative Check 
Address Use Range 
$00 

Sync Bytes ($87,$CD) 
$01 
$02 

Module Size (bytes) 
$03 
$04 

Module Name Offset Header 
$05 Parity 


$08 Header Parity Check CRC 


$09 
Execution Offset 
$0A 
$0B 
Permanent Storage Size 
$0C 


Module Body 


CRC Check Value 


$0D Mode Byte - (D S PE PW PRE W R) 


4-10 


OS-9’s Unified Input/Output System / 4 


OS-9 Interaction With Devices 


Device drivers often must wait for hardware to complete a task 
or for a user to enter data. Such a wait situation occurs if an 
SCF device driver receives a Read but there is no data is avail- 
able, or if it receives a Write and no buffer space is available. 
OS-9 drivers that encounter this situation should suspend the 
current process (via F$Sleep). In this way the driver allows other 
processes to continue using CPU time. 


The most efficient way for a driver to awaken itself and resume 
processing data is by using interrupt requests (IRQs). It is possi- 
ble for the driver to sleep for a number of system clock ticks and 
then check the device or buffer for a ready signal. The drawbacks 
to this technique are: 


e@ It requires the system clock to always remain active. 


@ It might require a large number of ticks (perhaps 20) for 
the device to become ready. Such a case leaves you with 
a dilemma. If you make the program sleep for two ticks, 
the system wastes CPU time while checking for device 
ready. If the driver sleeps 20 ticks, it does not have a 
good response time. 


An interrupt system allows the hardware to report to the CPU 
and the device drivers when the device is finished with an opera- 
tion. Using interrupts to its advantage, a device driver can set 
up interrupt handling to occur when a character is sent or 
received or when a disk operation is complete. There is a built-in 
polling facility for pausing and awakening processes. Here is a 
technique for handling interrupts in a device driver: 


1. Use the Init routine to place the driver interrupt service call 
(IRQSVC) routine in the IRQ polling sequence via an F$IRQ 
system call: 


Idd V.Port,u get address to poll 
leax IRGPOLL,per point to IRQ packet 
leay IRQSVC,pcr point to IRQ@ routine 
OS9 FS$IRQ add dev to poll sequence 
bes Error abnormal exit if error 


2. Ensure that driver programs waiting for their hardware, call 
the sleep routine. The sleep routine copies V.Busy to 
V.Wake. Then, it goes to sleep for some period of time. 
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3. When the driver program wakes up, have it check to see 
whether it was awakened by an interrupt or by a signal sent 
from some other process. 


Usually, the driver performs this check by reading the Ww 
V.Wake storage byte. The V.Busy byte is maintained by the 

file manager to be used as the process ID of the process 

using the driver. When V.Busy is copied into V.Wake, then 
V.Wake becomes a flag byte and an information byte. A non- 

zero Wake byte indicates that there is a process awaiting an 
interrupt. The value in the Wake byte indicates the process 

to be awakened by sending a wakeup signal as shown in the 
following code: 


Ida V.Busy,u get proc ID 

sta V.Wake,u arrange for wakeup 

andce #*IntMasks prep tor interrupts 

JLeeped Lax: #0 or any other tick time 

Cit signal test. 

Us? FSsleep await an IRQ 

ldx D.Proc geal proc dese ptr if 
signal test 

ldb- PeSignal>x is signal present? WwW 
Cit Signal test? 

pine Siglest Pe it 80 2 Signed 
test 

tst V.Wake,u LRG occur’? 

bre Sleepsv bra if not 


Note that the code labeled “if signal test” is only necessary 
if the driver wishes to return to the caller if a signal is sent 
without waiting for the device to finish. Also note that IRQs 
and FIRQs must be masked between the time a command is 
given to the device and the moving of V.Busy and V.Wake. If 
they are not masked, it is possible for the device IRQ to 
occur and the IRQSVC routine to become confused as to 
whether it is sending a wakeup signal or not. 


4-12 


OS-9’s Unified Input/Output System / 4 


When the device issues an interrupt, OS-9 calls the routine 
at the address given in F$IRQ with the interrupts masked. 
Make the routine as short as possible, and have it return 
with an RTS instruction. IRQSVC can verify that an inter- 
rupt has occurred for the device. It needs to clear the inter- 
rupt to retrieve any data in the device. Then the V.Wake 
byte communicates with the main driver module. If V.Wake 
is non-zero, clear it to indicate a true device interrupt and 
use its contents as the process ID for an F$Send system call. 
The F$Send call sends a wakeup signal to the process. Here 
is an example: 


Idx V.Port,u get device address 

Lat 7? is if real interrupt from device’? 
bne IRQSVC90 bra to error if not 

Ida Data,x get data from device 

sta 0,y 

lda V.Wake,u 

beq IRQSVC80 bra if none 

clr V.Wake,u clear it as flag to main 
routine 

ldb #S¢Wake,u get wakeup signal 

OS9 F$Send send signal to driver 


IRQSVC80 clrb clear carry bit Call is well) 


rts 


IRQSVC90 comb set carry bit Cis an IRQ call) 


rts 


Suspend State (Level Two only) 


The Suspend State allows the elimination of the F$Send system 
call during interrupt handling. Because the process is already in 
the active queue, it need not be moved from one queue to 
another. The device driver IRQSVC routine can now wake up the 
suspended main driver by clearing the process status byte sus- 
pend bit in the process state. Following are sample routines for 
the Sleep and IRQSVC calls: 


lda D.Proc Get process ptr 
sta V.Wake,u prep for re-awakening 


enable device to IRQ, give command, etc. 
bra Cmd50 enter suspend loop 


Cmd30 ldx D.Proc get ptr to process desc 
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lda P$State,x get state flag 
ora #Suspend put proc in suspend state 
sta P$State,x save it in proc desc 
andcc #*IntMasks unmask interrupts 
Idx #1 give ue time: slice 
O0S9 F$Sleep suspend Cin active queue) 
CmdS0 orce #IntMasks mask interrupts while 
changing state 
ldx D.Proc get proc desc addr Cif signal 
test) 
Ilda P$Signal,x get signal Cif signal test) 
beq SigProc tre if signal to be handled 
lda V.Wake,u true interrupt? 
bne Cmd30 bra if not 
andce #*IntMasks assure interrupts unmasked 


Note that D.Proc is a pointer to the process descriptor of the cur- 
rent process. Process descriptors are always allocated on 256- 
byte page boundaries. Thus, having the high order byte of the 
address is adequate to locate the descriptor. D.Proc is put in 
V.Wake as a dual value. In one instance, it is a flag byte indi- 
cating that a process is indeed suspended. In the other instance, 
it is a pointer to the process descriptor which enables the 
IRQSVC routine to clear the suspend bit. It is necessary to have 
the interrupts masked from the time the device is enabled until 
the suspend bit has been set. Making the interrupts ensure that 
the IRQSVC routine does not think it has cleared the suspend 
bit before it is even set. If this happens, when the bit is set the 
process might go into permanent suspension. The IRQSVC rou- 
tine sample follows: 


Idy V.Port,u get dev addr 

tst V.Wake,u is process awaiting 
IRQ? 

beg IRQSVCER no exit 


clear device interrupt 
exit if IRQ not from this device 


Ilda V.Wake,u get process ptr 

clrb 

stb V.Wake,u clear proc waiting FLAG 
Lin -d,% get process descriptor ptr 
Ida P$State,x get state flag 

anda # Suspend clear suspend state 
sta P$State,x save it 


a 
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clrb clear carry bit 
rts 

IRQSVCER comb set carry Bit 
rts 


Device Descriptor Modules 


Device descriptor modules are small, non-executable modules. 
Each one provides information that associates a specific I/O 
device with its logical name, hardware controller address(es), 
device driver, file manager name, and initialization parameters. 


Unlike the device drivers and file managers, which operate on 
classes of devices, each device descriptor tailors its functions to a 
specific device. Each device must have a device descriptor. 


Device descriptor modules use a standard module header, in 
which the module type is specified as code $Fx (device descrip- 
tor). The name of the module is the name by which the system 
and user know the device (the device name given in pathlists). 


The rest of the device descriptor header consists of the informa- 
tion in the following chart: 


Relative 

Address(es) Use 

$09,$0A The relative address of the file manager 
name string address 

$0B,$0C The relative address of the device driver 
name string 

$0D Mode/Capabilities: D S PE PW PRE WR 
(directory, single user, public execute, pub- 
lic write, public read, execute, write, read) 

$0E,$0F,$10 The absolute physical (24-bit) address of the 
device controller 

$11 The number of bytes (n bytes) in the ini- 
tialization table 

$12,$12+n Initialization table 


When OS-9 opens a path to the device, the system copies the ini- 
tialization table into the option section (PD.OPT) of the path 
descriptor. (See “Path Descriptors” in this chapter.) 
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The values in this table can be used to define the operating 
parameters that are alterable by the Get Status and Set Status 
system calls (I$GetStt and I$SetStt). For example, parameters 
that are used when initializing terminals define which control 
characters are to be used for functions such as backspace and 
delete. 


The initialization table can be a maximum of 32 bytes long. If 
the table is fewer than 32 bytes long, OS-9 sets the remaining 
values in the path descriptor to 0. 


You might wish to add devices to your system. If a similar device 
driver already exists, all you need to do is add the new hardware 
and load another device descriptor. Device descriptors can be in 
the boot module or they can be loaded into RAM from mass-stor- 
age files while the system is running. 


The following diagram illustrates the device descriptor format: 
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Relative 
Address 


$00 
$01 
$02 
$03 
$04 
$05 
$06 
$07 
$08 
$09 


$0A 
$0B 


$0D 
$0E 


$0F 
$10 


$11 
$12,$12+n 


Device Descriptor Format 


Use 


Sync Bytes ($87,$CD) 


Module Size (bytes) 


Offset to Module Name 


F$ (Type) $1 (Lang) 


Header Parity Check 


Offset to File Manager 
Name String 


Offset to Device Driver 
Name String 


Mode Byte 


Device Controller 
Absolute Physical Addr. 
(24 bit) 


Initialization Table Size 


(Initialization Table) 


(Name Strings, and so on) 


CRC Check Value 


a 


Check 


=) 
$9 
a 
© 


header 
parity 
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module 


CRC 
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Path Descriptors 


Every open path is represented by a data structure called a path 
descriptor (PD). The PD contains the information the file man- 
agers and device drivers require to perform I/O functions. 


PDs are 64 bytes long and are dynamically allocated and deallo- 
cated by the I/O manager as paths are opened and closed. 


They are internal data structures, that are not normally refer- 
enced from user or applications programs. The description of PDs 
is presented here mainly for those programmers who need to 
write custom file managers, device drivers, or other extensions to 
OS-9. 


PDs have three sections. The first section, which is ten bytes 
long, is the same for all file managers and device drivers. The 
information in the first section is shown in the following chart. 


Path Descriptor: Standard Information 


Relative Size 
Name Address (Bytes) Use 


PD.PD $00 1 Path number 

PD.MOD $01 i! Access mode: 1 = read, 2 = 
write, 3 = update 

PD.CNT $02 i Number of open paths using 
this PD 

PD.DEV $03 2 Address of the associated 
device table entry 

PD.CPR $05 1 Current process ID 

PD.RGS $06 2 Address of the caller’s regis- 
ter stack 

PD.BUF $08 2 Address of the 256-byte 
data buffer (if used) 

PD.FST $0A 22 Defined by the file manager 

PD.OPT $20 32 Reserved for the Getstat/ 


Setstat options 


PD.FST is 22-byte storage reserved for and defined by each type 
of file manager for file pointers, permanent variables, and so on. 


4-18 


OS-9’s Unified Input/Output System / 4 


PD.OPT is a 32-byte option area used for file or device operat- 
ing parameters that are dynamically alterable. When the path is 
opened, the I/O manager initializes these variables by copying 
the initialization table that is in the device descriptor module. 
User programs can change the values later, using the Get Status 
and Set Status system calls. 


PD.FST and PD.OPT are defined for the file manager in the 
assembly-language equate file (SCFDefs for the SCF manager or 
RBFDefs for the RBF manager). 
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Random Block File Manager 


The random block file manager (RBF manager) supports disk 
storage. It is a re-entrant subroutine package called by the I/O 
manager for I/O system calls to random-access devices. It main- 
tains the logical and physical file structures. 


During normal operation, the RBF manager requests allocation 
and deallocation of 256-byte data buffers. Usually, one buffer is 
required for each open file. When physical I/O functions are nec- 
essary, the RBF manager directly calls the subroutines in the 
associated device drivers. All data transfers are performed using 
256-byte data blocks (pages). 


The RBF manager does not deal directly with physical addresses 
such as tracks and cylinders. Instead, it passes to the device 
drivers address parameters, using a standard address called a 
logical sector number, or LSN. LSNs are integers from 0 to n-1, 
where n is the maximum number of sectors on the media. The 
driver translates the logical sector number to actual cylinder/ 
track/sector values. 


Because the RBF manager supports many devices that have dif- 
ferent performance and storage capacities, it is highly parame- 
ter-driven. The physical parameters it uses are stored on the 
media itself. 


On disk systems, the parameters are written on the first few 
sectors of Track 0. The device drivers also use the information, 
particularly the physical parameters stored on Sector 0. These 
parameters are written by the FORMAT program that initial- 
izes and tests the disk. 


Logical and Physical Disk Organization 


All disks used by OS-9 store basic identification, file structure, 
and storage allocation information on these first few sectors. 


LSN 0 is the identification sector. LSN 1 is the disk allocation 
map sector. LSN 2 marks the beginning of the disk’s ROOT 
directory. The following section tells more about LSN 0 and LSN 
ds 
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Identification Sector (LSN 0) 


LSN 0 contains a description of the physical and logical charac- 
teristics of the disk. These characteristics are set by the FOR- 
MAT command program when the disk is initialized. 


The following table gives the OS-9 mnemonic name, byte 
address, size, and description of each value stored in this LSN 0. 


Name 
DD.TOT 


DD.TKS 
DD.MAP 


DD.BIT 
DD.DIR 


DD.OWN 
DD.ATT 
DD.DSK 


DD.FMT 


DD.SPT 
DD.RES 
DD.BT 


DD.BSZ 


DD.DAT 
DD.NAM 


DD.OPT 


5-2 


Relative Size 
Address (Bytes) 


$00 


32 


Use 
Number of sectors on disk 


Track size (in sectors) 


Number of bytes in the alloca- 
tion bit map 


Number of sectors per cluster 


Starting sector of the ROOT 
directory 


Owner’s user number 
Disk attributes 


Disk identification (for internal 
use) 


Disk format, density, number 
of sides 


Number of sectors per track 
Reserved for future use 


Starting sector of the boot- 
strap file 


Size of the bootstrap file (in 
bytes) 


Time of creation (Y:M:D:H:M) 


Volume name in which the last 
character has the most signifi- 
cant bit set 


Path descriptor options 
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Disk Allocation Map Sector (LSN 1) 


LSN 1 contains the disk allocation map, which is created by 
FORMAT. This map shows which sectors are allocated to the 
files and which are free for future use. 


Each bit in the allocation map represents a sector or cluster of 
sectors on the disk. If the bit is set, the sector is considered to be 
in use, defective, or non-existent. If the bit is cleared, the corre- 
sponding cluster is available. The allocation map usually starts 
at LSN1. The number of sectors it requires varies according to 
how many bits are needed for the map. DD.MAP specifies the 
actual number of bytes used in the map. 


Multiple sector allocation maps allow the number of sectors/clus- 
ter to be as small as possible for high volume media. 


The FORMAT utility bases the size of the allocation map on the 
size and number of sectors per cluster. 


The DD.MAP value in LSN 0 specifies the number of bytes (in 
LSN 1) that are used in the map. 


Each bit on the disk allocation map corresponds to one sector 
cluster on the disk. The DD.BIT value in LSN 0 specifies the 
number of sectors per cluster. The number is an integral power 
of 2 (1, 2, 4, 8, 16, and so on). 


If a cluster is available, the corresponding bit is cleared. If it is 
allocated, non-existent, or physically defective, the corresponding 
bit is set. 


ROOT Directory 


This file is the parent directory of all other files and directories 
on the disk. It is the directory accessed using the physical device 
name (such as /D1). Usually, it immediately follows the Alloca- 
tion Map. The location of the ROOT directory file descriptor is 
specified in DD.DIR. The ROOT directory contains an entry for 
each file that resides in the directory, including other 
directories. 


File Descriptor Sector 


The first sector of every file is the file descriptor. It contains the 
logical and physical description of the file. 
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The following table describes the contents of the file descriptor. 


Relative Size 


Name Address (Bytes) Use 

FD.ATT $00 1 File attributes: DS PE PW PR 
E W R (see next chart) 

FD.OWN ~ $01 Z Owner’s user ID 

FD.DAT $03 5 a last modified: (Y M D H 

FD.LNK $08 1 Link count 

FD.SIZ $09 4 File size (number of bytes) 

FD.CREAT $0D 3 Date created (Y M D) 

FD.SEG $10 240 Segment list (see next chart) 


FD.ATT. (The attribute byte) contains the file permission bits. 
When set the bits indicate the following: 


Bit 7 Directory 

Bit 6 Single user 
Bit 5 Public execute 
Bit 4 Public write 
Bit 3 Public read 
Bit 2 Execute 

Bit 1 Write 

Bit 0 Read 


FD.SEG (the segment list) consists of a maximum of 48 5-byte 
entries that have the size and address of each file block in logical 
order. Each entry has the block’s 3-byte LSN and 2-byte size (in 
sectors). The entry following the last segment is zero. 


After creation, a file has no data segments allocated to it until 
the first write. (Write operations past the current end-of-file 
cause sectors to be added to the file. The first write is always 
past the end-of-file.) 


If the file has no segments, it is given an initial segment. Usu- 
ally, this segment has the number of sectors specified by the 
minimum allocation entry in the device descriptor. If, however, 
the number of sectors requested is more than the minimum, the 
initial segment has the requested number. 


0-4 


Random Block File Manager / 5 


Later expansions of the file usually are also made in minimum 
allocation increments. Whenever possible, OS-9 expands the last 
segment, instead of adding a segment. When the file is closed, 
OS-9 truncates unused sectors in the last segment. 


OS-9 tries to minimize the number of storage segments used in 
a file. In fact, many files have only one segment. In such cases, 
no extra Read operations are needed to randomly access any byte 
in the file. 


If a file is repeatedly closed, opened, and expanded, it can 
become fragmented so that it has many segments. You can avoid 
this fragmentation by writing a byte at the highest address you 
want to be used on a file. Do this before writing any other data. 


Directories 


Disk directories are files that have the D attribute set. A direc- 
tory contains an integral number of entries, each of which can 
hold the name and LSN of a file or another directory. 


Each directory entry contains 29 bytes for the filename, followed 
by the three bytes for the LSN of the file’s descriptor sector. The 
filename is left-justified in the field, with the most significant bit 
of the last character set. Unused entries have a zero byte in the 
first filename character position. 


Every disk has a master directory called the ROOT directory. 
The DD.DIR value in LSN 0 (identification sector) specifies the 
starting sector of the ROOT directory. 


The RBF Manager Definitions of the Path 
Descriptor 


As stated earlier in this chapter, the PD.FST section of the path 
descriptor is reserved for and defined by the file manager. The 
following table describes the use of this section by the RBF man- 
ager. For your convenience, it also includes the other sections of 
the PD. 
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Relative Size 


Name Address (Bytes) Use 
Universal Section (Same for all file managers and device drivers) 
PD.PD $00 1 Path number 
PD.MOD $01 1 Access mode 
1 = read, 
2 = write, 
3 = update 
PD.CNT $02 1 Number of open images (paths 
using this PD) 
PD.DEV $03 2 Address of the associated 
device table entry 
PD.CPR $05 1 Current process ID 
PD.RGS $06 2 Address of the caller’s 6809 
register stack 
PD.BUF $08 2 Address of the 256-byte data 


buffer (if used) 


Relative Size 


Name _— Address (Bytes) Use 
The RBF manager Path Descriptor Definitions (PD.FST Section) 
PD.SMF $0A 1 State flag: 
Bit 0 =current buffer is 
altered 
Bit 1 = current sector is in 
the buffer 


Bit 2 = descriptor sector is 
in the buffer 


PD.CP $0B 4 Current logical file position 
(byte address) 

PD.SIZ $S0F 4 File size 

PD.SBL $13 3 Segment beginning logical sec- 
tor number (LSN) 

PD.SBP $16 3 Segment beginning physical 


sector number (PSN) 
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Name 
PD.SSZ 


PD.DSK 
PD.DTB 


Name 
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Relative Size 
Address (Bytes) Use 


$19 3 Segment size 
$1C 2 Disk ID (for internal use only) 
$1K 2 Address of drive table 


Relative Size 
Address (Bytes) Use 


The RBF manager Option Section Definitions (PD.OPT Section) 


(Copied from the device descriptor) 


PD.DTP 


PD.DRV 
PDISTP 
PD.IYP 
PD.DNS 
PD.CYL 
PD.SID 

PD.VFY 
PD.SCT 


PD.TOS 


PD.ILV 
PD.SAS 
PD.TFM 


PD.EXTEN 


PD.STOFF 


$20 1 Device class: 
0 = SCF 
L:=> RBE 
2 = PIPE 
3 = SBF 
$21 i) Drive number (0..n) 
$22 1 Step rate 
$23 il Device type 
$24 1 Density capability 
$25 2 Number of cylinders (tracks) 
$27 i) Number of sides (surfaces) 
$28 1 0 = verify disk writes 
$29 y Default number of sectors per 
track 
$2B 2 Default number of sectors per 
track (Track 0) 
$2D 1 Sector interleave factor 
$2E 1 Segment allocation size 
$2F 1 DMA transfer mode 
$30 Z Path extension for record 
locking 
$32 1 Sector/track offsets 
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Relative Size 


Name Address (Bytes) Use 
(Not copied from the device descriptor): 
PD.ATT $33 1 File attributes 


(D S PE PW PRE W R) 
File descriptor PSN 
Directory file descriptor PSN 


PD.FD $34 
PD.DFD $37 
PD.DCP $3A 
PS.DVT $3E 


File’s directory entry pointer 


Address of the device table 
entry 


Do -& Wd 


Any values not determined by this table default to zero. 


RBF-Type Device Descriptor Modules 


This section describes the use of the initialization table con- 
tained in the device descriptor modules for RBF-type devices. 
The following values are those the I/O manager copies from the 
device descriptor to the path descriptor. 
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Relative Size 


Name Address (Bytes) Use 
$0-$11 Standard device descriptor 
module header 
IT.DTP $12 1 Device type: 
0 = SCF 
1 = RBF 
2 = PIPE 
3 = SBF 
IT.DRV $13 1 Drive number 
rrr $14 il Step rate 
LEY YP $15 i Device type (see RBF path 
descriptor) 
IT.DNS $16 ui Media density: 


Always 1 (double) 
(see following information) 


IT.CYL $17 Z Number of cylinders (tracks) 

IT.SID $19 | Number of sides 

IT. VFY $1A 1 0 = Verify disk writes 
1 = no verify 

IT.SCT $1B 2 Default number of sectors per 
track 

IT.TOS $1D 2 Default number of sectors per 
track (Track 0) 

IT. ILV $1F 1 Sector interleave factor 

IT.SAS $20 1 Minimum size of segment allo- 


cation (number of sectors to be 
allocated at one time) 


IT.DRV is used to associate a 1-byte integer with each drive 
that a controller handles. Number the drives for each controller 
as 0 to n-1, where n is the maximum number of drives the con- 
troller can handle. 
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IT.TYP specifies the device type (all types). 


Bit 0 — 0 = 5-inch floppy diskette 

Bit 5 — 0 = Non-Color Computer format 
1 = Color Computer format 

Bit 6 — 0 = Standard OS-9 format 
1 = Non-standard format 

Bit 7 — 0 = Floppy diskette 
1 = Hard disk 


IT.DNS specifies the density capabilities (floppy diskette only). 


Bit 0 — 0 = Single-bit density (FM) 
1 = Double-bit density (MFM) 
Bit 1 — 0 = Single-track density (5-inch, 48 tracks per 
inch) 
1 = Double-track density (5-inch, 96 tracks per 
inch) 


IT.SAS specifies the minimum number of sectors allowed at one 
time. 


RBF Record Locking 


Record locking is a general term that refers to methods designed 
to preserve the integrity of files that can be accessed by more 
than one user or process. The OS-9 implementation of record 
locking is designed to be as invisible as possible. This means 
that existing programs do not have to be rewritten to take 
advantage of record locking facilities. You can usually write new 
programs without special concern for multi-user activity. 


Record locking involves detecting and preventing conflicts during 
record access. Whenever a process modifies a record, the system 
locks out other procedures from accessing the file. It defers 
access to other procedures until it is safe for them to write to the 
record. The system does not lock records during reads; so, multi- 
ple processes can read the record at the same time. 
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Record Locking and Unlocking 


To detect conflicts, OS-9 must recognize when a record is being 
updated. The RBF manager provides true record locking on a 
byte basis. A typical record update sequence is: 


OS9 I$Read Program reads record 
RECORD IS LOCKED 


Program updates record 


OS9 I$Seek reposition to record 
OS9 I$¢Write record is rewritten 
RECORD IS RELEASED 


When a file is opened in update mode, any read causes locking 
of the record being accessed. This happens because the RBF 
manager cannot determine in advance if the record is to be 
updated. The record stays locked out until the next read, write, 
or close. 


However, when a file is opened in the read or execute modes, the 
system does not lock accessed records because the records cannot 
be updated in these two modes. 


A subtle but important problem exists for programs that interro- 
gate a data base and occasionally update its data. If you neglect 
to release a record after accessing it, the record might be locked 
up indefinitely. This problem is characteristic of record locking 
systems and you can avoid it with careful programming. 


Only one portion of a file can be locked out at a time. If an 
application requires more than one record to be locked out, open 
multiple paths to the same file and lock the record accessed by 
each path. RBF notices that the same process owns both paths 
and keeps them from locking each other out. 
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Non-Shareable Files 


Sometimes (although rarely), you must create a file that can 
never be accessed by more than one user at a time. To lock the 
file, you set the single-user (s) bit in the file’s attribute byte. You 
can do this by using the proper option when the file is created, 
or later using the OS-9 ATTR command. Once the single-user 
bit is set, only one user can open the file at a time. If other users 
attempt to open the file, Error 253 is returned. Note however, 
that non-shareable means only one path can be opened to a file 
at one time. Do not allow two processes to concurrently access a 
non-shareable file through the same path. 


More commonly, you need to declare a file as single-user only 
during the execution of a specific program. You can do this by 
opening the file with the single-user bit set. For example, sup- 
pose a process is sorting a file. With the file’s single-user bit set, 
OS-9 treats the file exactly as though it had a single-user attrib- 
ute. If another process attempts to open the file, OS-9 returns 
Error 253. 


You can duplicate non-shareable paths by using the I$Dup sys- 
tem call. This means that it can be inherited, and therefore 
accessible to more than one process at a time. Single-user means 
that the file can be opened only once. 


End-of-File Lock 


A special case of record locking occurs when a user reads or 
writes data at the end of a file, creating an HOF Lock. An EOF 
Lock keeps the end of the file locked out until a process performs 
a READ or WRITE that is not at the end of the file. It prevents 
problems that might otherwise occur when two users want to 
simultaneously extend a file. The EOF Lock is the only case in 
which a WRITE call automatically causes portions of a file to be 
locked out. An interesting and useful side effect of the EOF Lock 
function occurs if a program creates a file for sequential output. 
As soon as the program creates the file, EOF Lock is set and no 
other process can pass the writer in processing the file. For 
example, if an assembler redirects a listing to a disk file, and a 
spooler utility tries to print a line from the file before it is writ- 
ten, record locking makes the spooler wait and stay at least one 
step behind the assembler. 
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Deadlock Detection 


A deadly embrace, or deadlock, typically occurs when two pro- 
cesses attempt to gain control of two or more disk areas at the 
same time. If each process gets one area (locking out the other 
process), both processes become permanently stuck. Each waits 
for a segment that can never become free. This situation is not 
restricted to any particular record locking scheme or operating 
system. 


When a deadly embrace occurs, RBF returns a deadlock error 
(Error 254) to the process that caused OS-9 to detect the dead- 
lock. To avoid deadlocks, make sure that processes always access 
records of shared files in the same sequence. 


When a deadlock error occurs, it is not sufficient for a program 
to retry the operation that caused the error. If all processes use 
this strategy, none can ever succeed. For any process to proceed, 
at least one must cancel operation to release its control over a 
requesting segment. 


RBF-Type Device Driver Modules 


An RBF-type device driver module contains a package of subrou- 
tines that perform sector-oriented I/O to or from a specific hard- 
ware controller. Such a module is usually re-entrant. Because of 
this, one copy of one device driver module can simultaneously 
run several devices that use identical I/O controllers. 


The I/O manager allocates a permanent memory area for each 
device driver. The size of the memory area is given in the device 
driver module header. The I/O manager and the RBF manager 
use some of this area. The device driver can use the rest in any 
manner. This area is used as follows: 


The RBF Device Memory Area Definitions 


Relative Size 


Name Address (Bytes) Use 

V.PAGE $00 il Port extended address bits 
A20-A16 

V.PORT $01 2 Device base address (defined 


by the I/O manager) 
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Relative Size 


Name Address (Bytes) Use 

V.LPRC $03 1 ID of the last active process 
(not used by RBF device 
drivers) 

V.BUSY $04 if ID of the current process using 


driver (defined by RBF) 
0 = no current process 


V.WAKE ~ $05 1 ID of the process waiting for 
I/O completion (defined by the 
device driver) 


V.USER $06 0 Beginning of file manager spe- 
cific storage 
V.NDRV $06 1 Maximum number of drives 


the controller can use (defined 
by the device driver) 


$07 8 Reserved 
DRVBEG  $0F 0 Beginning of the drive tables 
TABLES $0F DRVMEN*N Space for number of tables 
reserved (7) 
FREE 0) Beginning of space available 
for driver 


These values are defined in files in the DEFS directory on the 
Development Package disk. 


TABLES. This area contains one table for each drive that the 
controller handles. (The RBF manager assumes that there are as 
many tables as indicated by V.NDRV.) Some time after the 
driver Init routine is called, the RBF manager issues a request 
for the driver to read LSN 0 from a drive table by copying the 
first part of LSN 0 (up to DD.SIZ) into the table. Following is 
the format of each drive table: 
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Relative Size 


Name Address (Bytes) Use 

DD.TOT $00 3 Number of sectors. 

DD.TKS $03 1 Track size (in sectors). 

DD.MAP $04 yi Number of bytes in the alloca- 
tion bit map. 

DD.BIT $06 2 Number of sectors per bit 
(cluster size). 

DD.DIR $08 3 Address (LSN) of the ROOT 
directory. 

DD.OWN ~~ $0B 2 Owner’s user number. 

DD.ATT $0D 1 Disk access attributes 
(D S PE PW PRE WR). 

DD.DSK SOE 2 Disk ID (a pseudo-random 
number used to detect diskette 
Swaps). 

DD.FMT $10 1 Media format. 

DD.SPT $11 vs Number of sectors per track. 


(Track 0 can use a different 
value specified by IT.TOS in 
the device descriptor.) 


DD.RES $13 2 Reserved for future use. 

DD.SIZ $15 0 Minimum size of device 
descriptor. 

V.TRAK $15 Py Number of the current track 


(the track that the head is on, 
and the track updated by the 
driver). 


V.BMB $17 1 Bit-map use flag: 
O = Bit map is not in use. 
(Disk driver routines 
must not alter V.BMB.) 


V.FILEHD $18 2 Open file list for this drive. 
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Relative Size 


Name Address (Bytes) Use 

V.DISKID $1A 2 Disk ID. 

V.BMAPSZ $1C 1 Size of bitmap. 

V.MAPSCT $1D 1 Lowest reasonable bitmap 
sector. 

V.RESBIT $1E 1 Reserved bitmap sector. 

V.SCTKOF $1F 1 Sector/track byte. 

V.SCOFST $20 1 Sector offset split from 
V.SCTKOF. 

V.TKOFST $21 1 Track offset split from 
V.SCTKOF. 

RESERVED $22 4 Reserved for future use. 

DRVMEN- $26 Size of each drive table. 


The format attributes (DD.FMT) are these: 


Bit BO = Number of sides 
0 = Single-sided 
1 = Double-sided 
Bit B1 = Density 
0 = Single-density 
1 = Double-density 
Bit B2 = Track density 
0 = Single (48 tracks per inch) 


1 = Double (96 tracks per inch) 


RBF Device Driver Subroutines 


Like all device driver modules, RBF device drivers use a stan- 
dard executable memory module format. 


The execution offset address in the module header points to a 
branch table that has six 3-byte entries. Each entry is typically 
a long branch (LBRA) to the corresponding subroutine. The 
branch table is defined as follows: 
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ENTRY LBRA 
LBRA 
LBRA 
LBRA 
LBRA 
LBRA 
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INIT 
READ 
WRITE 
GETSTA 
SETSTA 
TERM 


Initialize drive 
Read sector 
Write sector 

Get status 

Set status 
Terminate device 


Ensure that each subroutine exists with the C bit of the condi- 
tion code register cleared if no error occurred. If an error occurs, 
set the C bit and return an appropriate error code Register B. 


The rest of this chapter describes the RBF device driver subrou- 
tines and their entry and exit conditions. 
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Init Ititializes a device and the device’s memory 
area. 


Entry Conditions: 


Y = address of the device descriptor 
U = address of the device memory area 


Exit Conditions: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


e If you want OS-9 to verify disk writes, use the Request 
Memory system call (F$SRqMem) to allocate a 256-byte 
buffer area in which a sector can be read back and verified 
after a write. 


@ You must initialize the device memory area. For floppy 
diskette controllers, initialization typically consists of: 


1. Initializing V.NDRV to the number of drives with which 
the controller works 


2. Initializing DD.TOT (in the drive table) to a non-zero 
value so that Sector 0 can be read or written 


3. Initializing V.TRAK to $FF so that the first seek finds 
Track 0 


4. Placing the IRQ service routine on the IRQ polling list, 
using the Set IRQ system call (F$IRQ) 


5. Initializing the device control registers (enabling inter- 
rupts if necessary) 


e@ Prior to being called, the device memory area is cleared (set 
to zero), except for V.PAGE and V.PORT. (These areas con- 
tain the 24- bit device address.) Ensure the driver initial- 
izes each drive table appropriately for the type of diskette 
that the driver expects to be used on the corresponding 
drive. 
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Read Reads a 256-byte sector from a disk and 
places it in a 256-byte sector buffer. 


Entry Conditions: 


B = MSB of the disk’s LSN 

X = LSB of the disk’s LSN 

Y = address of the path descriptor 

U = address of the device memory area 


Exit Conditions: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 
@ The following is a typical routine for using Read: 


1. Get the sector buffer address from PD.BUF in the path 
descriptor. 


2. Get the drive number from PD.DRV in the path 
descriptor. 


3. Compute the physical disk address from the logical sec- 
tor number. 


4. Initiate the Read operation. 


5. Copy V.BUSY to V.WAKE. The driver goes to sleep and 
waits for the I/O to complete. (The IRQ service routine is 
responsible for sending a wakeup signal.) After awaken- 
ing, the driver tests V.WAKE to see if it is clear. If it 
isn’t clear, the driver goes back to sleep. 


@ Whenever you read LSN 0, you must copy the first part of 
this sector into the proper drive table. (Get the drive num- 
ber from PD.DRV in the path descriptor.) The number of 
bytes to copy is in DD.SIZ. Use the drive number (PD.DRV) 
to compute the offset for the corresponding drive table as 
follows: | 
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LDA PD.DRV,Y Get the drive number 

LDB #DRVMEN Get the size of a 
drive table 

MUL 

LEAX DRVBEG,U Get the address of 
the first table 

LE Ae.” shy oe Compute the address 
of the table 
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Write writes a 256-byte sector buffer to a disk. 


Entry Conditions: 


B = MSB of the disk LSN 

X  =LSB of the disk LSN 

Y = address of the path descriptor 

U = address of the device memory area 


Exit Conditions: 


CC =carry set on error 
B = error code 


Additional Information: 
@ Following is a typical routine for using Write: 


1. Get the sector buffer address from PD.BUF in the path 
descriptor. 


2. Get the drive number from PD.DRV in the path descriptor. 


3. Compute the physical disk address from the logical sector 
number. 


4. Initiate the Write operation. 


5. Copy V.BUSY to V.WAKE. The driver then goes to sleep 
and waits for the I/O to complete. (The IRQ service routine 
sends the wakeup signal.) After awakening, the driver tests 
V.WAKE to see if it is clear. If it is not, the driver goes 
back to sleep. If the disk controller cannot be interrupt-dri- 
ven, it is necessary to perform a programmed I/O transfer. 


6. If PF.VFY in the path descriptor is equal to zero, read the 
sector back in and verify that it is written correctly. Verifi- 
cation usually does not involve a comparison of all of the 
data bytes. 


e If disk writes are to be verified, the Init routine must 
request the buffer in which to place the sector when it is 
read back. Do not copy LSN 0 into the drive table when 
reading it back for verification. 
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@ Use the drive number (PD.DRV) to compute the offset to 
the corresponding drive table as shown for the Read 
routine. 
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Getstats and Setstats 


Reads or changes device’s operating parameters. 


Entry Conditions: 


U = address of the device memory area 
Y = address of the path descriptor 
A = status code 


Exit Conditions: 


B = error code (if any) 
CC =carry set on error 


Additional Information: 


@ Get/set the device’s operating parameters (status) as speci- 
fied for the Get Status and Set Status system calls. Getsta 
and Setsta are wild card calls. 


@ It might be necessary to examine or change the register 
stack that contains the values of the 6809 register at the 
time of the call. The address of the register stack is in 
PD.RGS, which is located in the path descriptor. You can 
use the following offsets to access any value in the register 


stack: 
Relative 

Reg. Addr. Size 6809 Reg. 
R$CC $00 i) Condition Code Reg. 
R$D $01 2 Register D 
R$A $01 if Register A 
R$B $02 1 Register B 
RSDP $03 1 Register DP 
R$X $04 2 Register X 
RSY $06 2 Register Y 
R$U $08 Z Register U 
R$PC $0A 2 Program Counter 


@ Register D overlays Registers A and B. 
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Term Terminate a device. 


Entry Conditions: 
U = address of the device memory area 


Exit Conditions: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 


@ This routine is called when a device is no longer in use in 
the system (when the link count of its device descriptor 
module becomes zero). 


@ Following is a typical routine for using Term: 
1. Wait until any pending I/O is completed. 
2. Disable the device interrupts. 
3. Remove the device from the IRQ polling list. 
4 


. If the Init routine reserved a 256-byte buffer for verify- 
ing disk writes, return the memory with the Return 
Sysmem system call (F$SRtMem). 
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IRQ Service Routine 


Services device interrupts. 


Additional Information: 


@ The IRQ Service routine sends a wakeup signal to the pro- 
cess indicated by the process ID in V.WAKE when the I/O 
is complete. It then clears V.WAKE as a flag to indicate to 
the main program that the IRQ has indeed occurred. 


@ When the IRQ service routine finishes servicing an inter- 
rupt it must clear the carry and exit with an RTS 
instruction. 


e@ Although this routine is not included in the device driver 
module branch table and is not called directly by the RBF 
manager, it is a key routine in interrupt-driven drivers. Its 
function is to: 


1. Service the device interrupts (receive data from device or 
send data to it). The IRQ service routine puts its data 
into and get its data from buffers that are defined in the 
device memory area. 


2. Wake up a process that is waiting for I/O to be com- 
pleted. To do this, the routine checks to see if there is a 
process ID in V.WAKE (if the bit is non-zero); if so, it 
sends a wakeup signal to that process. 


3. If the device is ready to send more data, and the output 
buffer is empty, disable the device’s ready to transmit 
interrupts. 
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Boot (Bootstrap Module) 


Loads the boot file into 


Entry Conditions: 


None 


Exit Conditions: 


D- = size of the boot file (in bytes) 

X = address at which the boot file was loaded into memory 
CC =carry set on error 

B = error code (if any) 


Additional Information: 


@ The Boot module is not part of the disk driver. It is a sepa- 
rate module that is stored on the boot track of the system 
disk with OS9P1 and REL. 


e The bootstrap module contains one subroutine that loads 
the bootstrap file and related information into memory. It 
uses the standard executable module format with a module 
type of $C. The execution offset in the module header con- 
tains the offset to the entry point of this subroutine. 


@ The module gets the starting sector number and size of the 
OS9Boot file from LSN 0. OS-9 allocates a memory area 
large enough for the Boot file. Then, it loads the Boot file 
into this memory area. 


@ Following is a typical routine for using Boot: 


1. Read LSN 0 from the disk into a buffer area. The Boot 
module must pick its own buffer area. LSN 0 contains 
the values for DD.BT (the 24-bit LSN of the bootstrap 
file), and DD.BSZ (the size of the bootstrap file in bytes). 


2. Get the 24-bit LSN of the bootstrap file from DD.BT. 


3. Get the size of the bootstrap file from DD.BSZ. The Boot 
module is contained in one logically contiguous block 
beginning at the logical sector specified in DD.BT and 
extending for DD.BSZ/256 +1 sectors. 
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4. Use the OS-9 Request Sysmem system call (F$SRqMem) 
to request the memory area in which the Boot file is 
loaded. 


5. Read the Boot file into this memory area. 


6. Return the size of the Boot file and its location. Boot file 
is loaded. 
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Sequential Character 
File Manager 


The Sequential Character File Manager (SCF) supports devices 
that operate on a character-by-character basis. These include 
terminals, printers, and modems. 


SCF is a re-entrant subroutine package. The I/O manager calls 
the SCF manager for I/O system handling of sequential, charac- 
ter-oriented devices. The SCF manager includes the extensive I/O 
editing functions typical of line-oriented operation, such as: 


@ backspace 

@ line delete 

® line repeat 

@ auto line feed 

® screen pause 

@ return delay padding 


The SCF-type device driver modules are CC3IO, PRINTER, and 
RS-232. They run the video display, printer, and serial ports 
respectively. See the OS-9 Commands manual for additional 
Color Computer I/O devices. 


SCF Line Editing Functions 


The SCF manager supports two sets of read and write functions. 
I$Read and I$Write pass data with no modification. I$ReadLn 
and I$WritLn provide full line editing of device functions. 


Read and Write 


The Read and Write system calls to SCF-type devices correspond 
to the BASICO9 GET and PUT statements. While they perform 
little modification to the data they pass, they do filter out key- 
board interrupt, keyboard terminate, and pause character. (Edit- 
ing is disabled if the corresponding character in the path 
descriptor contains a zero.) 
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Carriage returns are not followed by line feeds or nulls automat- 
ically, and the high order bits are passed as sent/received. 


Read Line and Write Line 


The Read Line and Write Line system calls to SCF-type devices 
correspond to the BASICO9 INPUT, PRINT, READ, and WRITE 
statements. They provide full line editing of all functions enabled 
for a particular device. 


The system initializes I$ReadLn and I$WritLn functions when 
you first use a particular device. (OS-9 copies the option table 
from the device descriptor table associated with the specific 
device. ) 


Later, you can alter the calls—either from assembly-language 
programs (using the Get Status system call), or from the key- 
board (using the TMODE command). All bytes transferred by 
Readln and Writln have the high order bit cleared. 


SCF Definitions of the Path Descriptor 


The PD.FST and PD.OPT sections of the path descriptor are 
reserved for and used by the SCF file manager. 


The following table describes the SCF manager’s use of PD.FST 
and PD.OPT. For your convenience, the table also includes the 
other sections of the PD. 


The PD.OPT section contains the values that determine the line 
editing functions. It contains many device operating parameters 
that can be read or written by the Set Status or Get Status sys- 
tem call. Any values not set by this table default to zero. 


Note: You can disable most of the editing functions by set- 
ting the corresponding control character in the path 
descriptor to zero. You can use the Set Status system call 
or the TMODE command to do this. Or, you can go a step 
further by setting the corresponding control character value 
in the device descriptor module to zero. 


To determine the default settings for a specific device, you can 
inspect the device descriptor. 
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Relative Size 


Name Address (Bytes) Use 
ay Universal Section (Same for all file managers) 
PD.PD $00 | Path number 
PD.MOD $01 1 Access mode: 
1 = read 
2 = write 
3 = update 
PD.CNT $02 1 Number of open images (paths 
using this PD) 
PD.DEV $03 2 Address of the associated 
device table entry 
PD.CPR $05 i Current process ID 
PD.RGS $06 Z Address of the caller’s 6809 
register stack 
PD.BUF $08 2 Address of the 256-byte data 
co” buffer (if used) 
Relative Size 
Name Address (Bytes) Use 
SCF Path Descriptor Definitions (PD.FST Section) 
PD.DV2 $0A 2 Device table address of the sec- 
ond (echo) device 
PD.RAW $0C 1 Edit flag: 
0 = raw mode 
1 = edit mode 
PD.MAX $0D 2 Read Line maximum character 
count 
PD.MIN $0F 1 Devices are mine if cleared 
PD.STS $10 Status routine module address 
O PpDSTM $12 2 Reserved for status routine 
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Relative Size Use 
Name Address (Bytes) 


SCF Option Section Definition (PD.OPT Section) 
(Copied from the device descriptor) 


PD.DTP $20 1 Device class: 
0 = SCF 
i = RBE 
2 = PIPE 
o = SBE 
PD.UPC $21 i Case: 
QO = upper and lower 
1 = upper only 
PD.BSO $22 iL Backspace: 


0 = backspace 
1 = backspace, space and 
backspace 


PD.DLO $23 1 Delete: 
0 = backspace over line 
1 = carriage return, line 


feed 
PD.EKO $24 : Echo: 
0 = no echo 
PD.ALF S20 1 Auto line feed: 
0 = no auto line feed 
PD.NUL $26 1 End-of-line null count: 


n = number of nulls ($00) 
sent after each carriage 
return or carriage return 
and line feed (n = $00-$FF) 


PD.PAU $27 1 End of page pause: 

0 = no pause 
PD.PAG $28 1 Number of lines per page 
PD.BSP $29 1 Backspace character 
PD.DEL $2A 1 Delete-line character 
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Relative Size 
Name Address (Bytes) Use 


SCF Option Section Definition continued (PD.OPT Section) 
PD.EOR $2B 1 End-of-record character (End- 


of-line character) Read only. 
Normally set to $0D: 


0 = Terminate read-line 
only at the end of the 
file 

PD.EOF $2C 1 End-of-file character (read 
only) 

PD.RPR $2D 1 Reprint-line character 

PD.DUP $2E 1 Duplicate-last-line character 

PD.PSC $2F il Pause character 

PD.INT $30 1 Keyboard-interrupt character 

PD.QUT $31 1 Keyboard-terminate character 

PD.BSE $32 if Backspace-echo character 

PD.OVF $33 1 Line-overflow character (bell 
(CTRL }(G}) 

PD.PAR $34 i Device-initialization value 
(parity) 

PD.BAU $35 1 Software setable baud rate 

PD.D2P $36 2 Offset to second device name 
string 

PP.XON $38 1 ACIA XON char 

PD.XOFF $39 1 ACIA XOFF char 

PD.ERR $3A 1 Most recent I/O error status 

PD.TBL $3B 2 Copy of device table address 

PD.PLP $3D 2 Path descriptor list pointer 

PD.PST $3F 1 Current path status 
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PD.EOF specifies the end-of-file character. If this is the first 
and only character that is input to the SCF device, SCF returns 
an end-of-file error on Read or ReadIn. 


PD.PSC specifies the pause character, which suspends output to 
the device before the next end-of-record character. The pause 
character also deletes any type-ahead input for ReadIn. 


PD.INT specifies the keyboard-interrupt character. When the 
character is received, the system sends a keyboard terminate 
signal to the last user of a path. The character also terminates 
the current I/O request (if any) with an error identical to the 
keyboard interrupt signal code. 


PD.QUT specifies the keyboard-terminate character. When this 
character is received, the system sends a keyboard terminate 
signal to the last user of a path. The system also cancels the 
current I/O request (if any) by sending error code identical to the 
keyboard interrupt signal code. 


PD.PAR specifies the parity information for external serial 
devices. 


PD.BAU specifies baud rate, word length and stop bit informa- 
tion for serial devices. 


PD.XON contains either the character used to enable transmis- 
sion of characters or a null character that disables the use of 
XON. 


PD.XOFF contains either the character used to disable trans- 
mission of characters or a null character that disables the use of 
XOFF. 


SCF-Type Device Descriptor Modules 


The following chart shows how the initialization table in the 
device descriptors is used for SCF-type devices. The values are 
those the I/O manager copies from the device descriptor to the 
path descriptor. 


An SCF editing function is turned off if its corresponding value 
is set to zero. For example, if IT.EOF is set to zero, there is no 
end-of-file character. 
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Name 


(header) 


IT.DVC 


LELUPG 


IT.BSO 


IT.DLO 


IT.EKO 


IT.ALF 


IT.NUL 
IT.PAU 


IT.PAG 
IT.BSP 
IT.DEL 
IT.EOR 
IT. EOF 
PRP 
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Relative 


Size 


Address (Bytes) Use 


$00- 
11 


$12 


$13 


$14 


$15 


$16 


$17 


$18 
$19 


$1A 
$1B 
$1C 
$1D 
$1E 
$1F 


Se Be Se BS SS 


Standard device descriptor 
module header 


Device class: 


= S5CF 

lL =RBP 

2 = PIPE 

3 = SBE 
Case: 


= upper- and lowercase 
1 = uppercase only 


Backspace: 
0 = backspace 
1 = backspace, then space 
and backspace 


Delete: 
0 = backspace over line 
1 = carriage return 


Echo: 
0 = echo off 


Auto line feed: 
0 = auto line feed disabled 


End-of-line null count 
Pause: 

O = end-of-page pause 

disabled 

Number of lines per page 
Backspace character 
Delete-line character 
End-of-record character 


End-of-file character 


Reprint-line character 
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Relative Size 


Name Address (Bytes) Use 

IT.DUP $20 1 Duplicate-last-line character 

IT.PSC $21 1 Pause character 

IEINT $22 i Interrupt character 

IT.QUT $23 i Quit character 

IT.BSE $24 i Backspace echo character 

IT.OVF $25 1 Line-overflow character (bell) 

IT.PAR $26 1 Initialization value—used to 
initialize a device control reg- 
ister when a path is opened to 
it (parity) 

IT.BAU $27 | Baud rate 

IT. D2P $28 2 Attached device name string 
offset 

IT.XON $2A 1 X-ON character 

IT. XOFF $2B 1 X-OFF character 

IT.COL $2C 1 Number of columns for display 

IT.ROW $2D i) Number of rows for display 

IT.WND $2E 1 Window number 

IT. VAL $2F 1 Data in rest of descriptor is 
valid 

TESLyY $30 1 Window type 

IE.CPA $31 i! X cursor position 

tid WE Gs Sd $32 iL Y cursor position 

IT.FGC $33 1 Foreground color 

IT.BGC $34 1 Background color 

IT.BDC $35 1 Border color 
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SCF-Type Device Driver Modules 


An SCF-type device driver module contains a package of subrou- 
tines that perform raw (unformatted) data I/O transfers to or 
from a specific hardware controller. Such a module is usually re- 
entrant so that one copy of the module can simultaneously run 
several devices that use identical I/O controllers. The 
I/O manager allocates a permanent memory area for each con- 
troller sharing the driver. 


The size of the memory area is defined in the device driver mod- 
ule header. The I/O manager and SCF use some of the memory 
area. The device driver can use the rest in any way (typically as 
variables and buffers). Typically, the driver uses the area as 
follows: 


Relative Size 


Name Address (Bytes) Use 
V.PAGE $00 1 Port extended 24 bit address 
V.PORT $01 2 Device base address (defined 
by the I/O manager) 
V.LPRC $03 il ID of the last active process 
V.BUSY $04 1 ID of the active process 
(defined by RBF): 
O = no active process 
V.WAKE $05 1 ID of the process to reawaken 


after the device completes I/O 
(defined by the device driver): 
O = no waiting process 


V.USER $06 0 Beginning of file manager 
specific storage 
V.TYPE $06 1 Device type or parity 
V.LINE $07 1 Lines left until the end of the 
page 
V.PAUS $08 i! Pause request: 
O = no pause requested 
V.DEV2 $09 Z Attached device memory area 
V.INTR $0B i Interrupt character 
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Relative Size 


Name Address (Bytes) Use 

V.QUIT $0C 1 Quit character 

V.PCHR $0D 1 Pause character 

V.ERR $0E 1 Error accumulator 

V.XON $0F : XON character 

V.XOFF $10 1 XOFF character 

V. KANJI $11 1 Reserved 

V.KBUF $12 2 Reserved 

V.MODADR $14 2 Reserved 

V.PDLHD $16 2 Path descriptor list header 

V.RSV $18 5 Reserved 

V.SCF $1D 0 End of SCF memory 
requirements 

FREE $1D 0 Free for the device driver to 
use 


V.LPRC contains the process ID of the last process to use the 
device. The IRQ service routine sends this process the proper sig- 
nal if it receives a quit character or an interrupt character. 
V.LPRC is defined by SCF. 


V.BUSY contains the process ID of the process that is using the 
device. (If the device is not being used, V.BUSY contains a zero.) 
The process ID is used by SCF to prevent more than one process 
from using the device at the same time. V.BUSY is defined by 
SCF. 


SCF Device Driver Subroutines 


Like all device drivers, SCF device drivers use a standard exe- 
cutable memory module format. 


The execution offset address in the module header points to a 
branch table that has six 3-byte entries. Each entry is typically 
an LBRA to the corresponding subroutine. The branch table is 
defined as follows: 
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ENTRY LBRA INET Initialize driver 
LBRA READ Read character 
LBRA WRITE Write character 
LBRA GETSTA Get status 
LBRA SETSTA Set status 
LBRA TERM Terminate device 


If no error occurs, each subroutine exits with the C bit in the 
Condition Code Register cleared. If an error occurred, each sub- 
routine sets the C bit and returns an appropriate error code in 
Register B. 


The rest of this chapter describes these subroutines and their 
entry and exit conditions. 
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Init Initializes device control registers, and 
enables interrupts if necessary. 


Entry Conditions: 

Y = address of the device descriptor 

U = address of the device memory area 
Exit Conditions: 

CC =carry set on error 

B = error code (if any) 
Additional Information: 


e@ Prior to being called, the device memory area is cleared (set 
to zero), except for V.PAGE and V.PORT. (V.PAGE and 
V.PORT contain the device address.) There is no need to 
initialize the part of the memory area used by the I/O 
manager and SCF. 


@ Follow these steps to use Init: 
1. Initialize the device memory area. 


2. Place the IRQ service routine on the IRQ polling list, 
using the Set IRQ system call (F$IRQ). 


3. Initialize the device control registers. 


6-12 


Sequential Character File Manager / 6 


Read _ Reads the next character from the input 
buffer. 


Entry Conditions: 


Y = = address of the path descriptor 
U = address of the device memory area 


Exit Conditions: 


A =character read 
CC =carry set on error 
B= error code (if any) 


Additional Information: 
@ This is a step by step description of a Read operation: 
1. Read gets the next character from the input buffer. 


2. If no data is ready, Read copies its process ID from 
V.BUSY into V.WAKE. It then uses the Sleep system 
call to put itself to sleep. 


3. Later, when Read receives data, the IRQ service rou- 
tine leaves the data in a buffer. Then, the routine 
checks V.WAKE to see if any process is waiting for the 
device to complete I/O. If so, the IRQ service routine 
sends a wakeup signal to the waiting process. 


e@ Data buffers are not automatically allocated. If a buffer is 
used, it defines it in the device memory area. 
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Write sends a character (places a data byte in 
an output buffer) and enables the device 
output interrupts. 


Entry Conditions: 


A =character to write 
Y = address of the path descriptor 
U = _ = address of the device memory area 


Exit Conditions: 


CC 
B 


carry set on error 
error code (if any) 


Additional Information: 


e If the data buffer is full, Write copies its process ID from 
V.BUSY into V.WAKE. Write then puts itself to sleep. 


Later, when the IRQ service routine transmits a character 
and makes room for more data, it checks V.WAKE to see if 
there is a process waiting for the device to complete I/O. If 
there is, the routine sends a wakeup signal to that process. 


e Write must ensure that the IRQ service routine that starts 
it begins to place data in the buffer. After an interrupt is 
generated, the IRQ service routine continues to transmit 
data until the data buffer is empty. Then, it disables the 
device’s ready-to-transmit interrupts. 


@ Data buffers are not allocated automatically. If a buffer is 
used, define it in the device memory area. 
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Getsta and Setsta 


Gets/sets device operating parameters (status) as 
specified for the Get Status and Set Status system 
calls. Getsta and Setsta are wildcard calls. 


Entry Conditions: 


A _ = depends on the function code 
Y = address of the path descriptor 
U = address of the device memory area 


Other registers depend on the function code. 


Exit Conditions: 


B = error code (if any) 
CC =carry set on error 
Other registers depend on the function code 


Additional Information: 


@ Any codes not defined by the I/O manager or SCF are 
passed to the device driver. 


@ You might need to examine or change the register stack 
that contains the values of the 6809 registers at the time of 
the call. The address of the register stack can be found in 
PD.RGS, which is located in the path descriptor. 


@ You can use the following offsets to access any value in the 
register packet: 


Relative Size 
Name Address (Bytes) 6809 Register 
R$CC $00 1 Condition Codes Register 
R$D $01 0 Register D 
R$A $01 1 Register A 
R$B $02 1 Register B 
R$DP $03 il Register DP 
R$X $04 2 Register X 
R$Y $06 2 Register Y 
R$U $08 2 Register U 
R$PC $0A 2 Program Counter 


The function code is retrieved from the R$B on the user stack. 
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Term. Terminates a device. Term is called when a 
device is no longer in use (when the link 
count of the device descriptor module 
becomes zero). 


Entry Conditions: 


U = pointer to the device memory area 


Exit Conditions: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 
@ To use Term: 


1. Wait until the IRQ service routine empties the output 
buffer. 


2. Disable the device interrupts. 
3. Remove the device from the IRQ polling list. 


@ When Term closes the last path to a device, OS-9 returns 
to the memory pool the memory that the device used. If the 
device has been attached to the system using the I$Attach 
system call, OS-9 does not return the static storage for the 
driver until an I$Detach call is made to the device. Mod- 
ules contained in the Boot file are never terminated, even if 
their link counts reach 0. 
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IRQ Service Routine 


Receives device interrupts. When I/O is complete, the 
routine sends a wakeup signal to the process identi- 
fied by the process ID in V.WAKE. The routine also 
clears V.WAKE as a flag to indicate to the main pro- 
gram that the IRQ has occurred. 


Additional Information: 


@ The IRQ Service Routine is not included in device driver 
branch tables, and is not called directly by SCF. However, it 
is a key routine in device drivers. 


@ When the IRQ Service routine finishes servicing an inter- 
rupt, the routine must clear the carry and exit with an 
RTS instruction. 


@ Here is a typical sequence of events that the IRQ Service 
Routine performs: 


ki 


Service the device interrupts (receive data from the 
device or send data to it). Ensure this routine puts its 
data into and get its data from buffers that are defined 
in the device memory area. 


Wake up any process that is waiting for I/O to complete. 
To do this, the routine checks to see if there is a pro- 
cess ID in V.WAKE (a value other than zero); if so, it 
sends a wakeup signal to that process. 


If the device is ready to send more data, and the output 
buffer is empty, disable the device’s ready-to-transmit 
interrupts. 


If a pause character is received, set V.PAUS in the 
attached device storage area to a value other than zero. 
The address of the attached device memory area is in 
V.DEV2. 


V.PAUS in the attached device storage area to non-zero 
value. The address of the attached device memory area 
is in V.DEV2. 


If a keyboard terminate or interrupt character is 
received, signal the process in V.LPRC (last known 
process) if any. 
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The Pipe File Manager 
(PIPEMAN) 


The Pipe file manager handles control of processes that use 
paths to pipes. Pipes allow concurrently executing processes to 
send each other data by using the output of one process (the 
writer) as input to a second process (the reader). The reader gets 
input from the standard input. The exclamation point (!) opera- 
tor specifies that the input or output is from or to a pipe. The 
Pipe file manager allocates a 256-byte block and a path descrip- 
tor for data transfer. The Pipe file manager also determines 
which process has control of the pipe. The Pipe file manager has 
the standard file manager branch table at its entry point: 


PipeEnt l|bra Create 
Ibra Open 
lIbra MakDir 
Ibra ChgDir 
lbra Delete 
lbra Seek 
lbra PRead 
lbra PWrite 
lbra PRdLn 
lbra PWrLn 
lbra Getstat 
Ibra Putstat 
lbra Close 


You cannot use MakDir, ChgDir, Delete, and Seek with pipes. If 
you try to do so, the system returns ESUNKSVC (unknown ser- 
vice request). Getstat and Putstat are also no-action service rou- 
tines. They return without error. 


Create and Open perform the same functions. They set up the 
256-byte data exchange buffer, and save several addresses in the 
path descriptor. 


The Close request checks to see if any process is reading or writ- 
ing through the pipe. If not, OS-9 returns the buffer. 


PRead, PWrite, PRdLn, and PWrLn read data from the buffer 
and write data to it. 
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The ! operator tells the Shell that processes wish to communicate 
through a pipe. For example: 


preci 4 proce ENTER 


In this example, shell forks Procl with the standard output path 
to a pipe, and forks Proc2 with the Standard input path from a 


pipe. 
Shell can also handle a series of processes using pipes. Example: 
procl 1 proce *' prees. proc4 (ENTER | 


The following outline shows how to set up pipes between 
processes: 


Open /pipe save path in variable x 
Dup path #1 save stdout in variable y 
Dup x make path available 
Fork proct HUT pipe in Sidgeuat 
(Dup uses lowest available) 
Close #1 make path available 
Dup y restore stdout 
Close y make path available 
Dup path #9 save stdin in Y 
Close #9 make path available 
Dup x pul pipe in. stdin 
rork 2 Tork process < 
Close #9Q make path available 
Dup y restore stdin 
Close x no longer needed 
Close y no longer needed 
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Example: The following example shows how an application can 
initiate another process with the stdin and stdout routed 


through a pipe. 


Upen /pipel save 
pen ¥ pLpec save 
Dup @ save 
Dup 1 Save 
Close @ make 
Close 1 make 
Dup a make 
Dup 6b make 
Fork new process 


Close @ make 


Patt: 27 Vatianic a 
path in variable b 
stdin in variable x 
stdout in variable y 
path available 

path available 

pipet Stain 

pipee Stdout 


path available 


Close 1 make path available 

Dup x restore staan 

Dup y restore stdout 

Return aé&b return pipe path: numbers to caller 


Chapter 8 
System Calls 


System calls are used to communicate between the OS-9 operat- 
ing system and assembly-language programs. There are two 
major types of calls—I/O calls and function calls. 


Function calls include user mode calls and system mode calls. 


Each system call has a mnemonic name. Names of I/O calls start 
with I$. For example, the Change Directory call is I$ChgDir. 
Names of function calls start with F$. For example, the Allocate 
Bits call is F$Al]Bit. The names are defined in the assembler- 
input conditions equate file called OS9Defs. 


System mode calls are privileged. You can execute them only 
while OS-9 is in the system state (when it is processing another 
system call, executing a file manager or device driver, and so 
on). 


System mode calls are included in this manual primarily for pro- 
grammers writing device drivers and other system-level 
applications. 


Calling Procedure 


To execute any system calls, you need to use an SWI2 
instruction: 


1. Load the 6809 registers with any appropriate parameters. 


2. Execute an SWI2 instruction, followed immediately by a con- 
stant byte, which is the request code. In the references in 
this chapter, the first line is the system call name (for exam- 
ple Close Path) and the second line contains the call’s mne- 
monic name (for example [$Close), the software interrupt 
Code 2 (103F), and the call’s request code (for example, 8F) 
in hexadecimal. 


3. After OS-9 processes the call, it returns any parameters in 
the 6809 registers. If an error occurs, the C bit of the condi- 
tion code register is set, and Register B contains the appro- 
priate error code. This feature permits a BCS or BCC 
instruction immediately following the system call to branch 
either if there is an error or if no error occurs. 
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As an example, here is the Close system call: 


LDA PATHNUM 


SWIe2 
FCB $8F 
BCS ERROR 


You can use the assembler’s OS9 directive to simplify the call, as 
follows. 


LDA PATHNUM 
OSs I$¢Close 
BCS ERROR 


The ASM assembler allows any combination of upper- or lower- 
case letters. The RMA assembler, included in the OS-9 Level 
Two Development Pak, is case sensitive. The names in this man- 
ual have been spelled with upper and lower case letters, match- 
ing the defs for RMA. 


I/O System Calls 


OS-9’s I/O calls are easier to use than many other systems’ I/O 
calls. This is because the calling program does not have to allo- 
cate and set up file control blocks, sector buffers, and so on. 


Instead, OS-9 returns a 1-byte path number whenever a process 
opens a path to a file or device. Until the path is closed, you can 
use this path number in later I/O requests to identify the file or 
device. 


In addition, OS-9 allocates and maintains its own data struc- 
tures; so, you need not deal with them. 


System Call Descriptions 


The rest of this chapter consists of the system call descriptions. 
At the top of each description is the system call name, followed 
by its mnemonic name, the SWI2 code and the request code. 
Next are the call’s entry and exit conditions, followed by addi- 
tional information about the code where appropriate. 


In the system call descriptions, registers not specified as entry 
or exit conditions are not altered. Strings passed as parameters 
are normally terminated with a space character and end-of-line 
character, or with Bit 7 of the last character set. 
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If an error occurs on a system call, the C bit of Register CC is 
set, and Register B contains the error code. If no error occurs, 
the C bit is clear, and Register B contains a value of zero. 


User Mode System Calls Quick Reference 


Following is a summary of the User Mode System Calls refer- 
enced in this chapter: 


FSAIIBit 
F$Chain 
F$CmpNam 
F$CpyMem 
F$CRC 
F$DelBit 
FSExit 
F$Fork 
F$GBIkMp 
F$GModDr 
F$GPrDsc 
F$Icpt 
F$ID 
F$Link 
F$Load 
FSMem 
FSNMLink 


FSNMLoad 


F$Perr 
F$PrsNam 
F$SchBit 


Sets bits in an allocation bit map 
Chains a process to a new module 
Compares two names 

Copies external memory 

Generates a cyclic redundancy check 
Deallocates bits in an allocation bit map 
Terminates a process 

Starts a new process 

Gets a copy of a system block map 
Gets a copy of a module directory 
Gets a copy of a process descriptor 
Sets a signal intercept trap 

Returns a process ID 

Links to a memory module 

Loads a module from mass storage 
Changes a process’s data area size 


Links to a module; does not map the mod- 
ule into the user’s address space 


Loads a module but does not map it into the 
user’s address space 


Prints an error message 
Parses a pathlist name 


Searches a bit map 
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F$Send 
F$Sleep 
F$SPrior 
F$SSWI 
F$STime 
F$SUser 
F$Time 
F$UnLink 
F$UnLoad 
F$Wait 
I$Attach 
I$Chgdir 
I$Close 
I$Create 
I$Delete 
I$DeletX 
I$Detach 
I$Dup 
I$GetStt 
I$MakDir 
I$Open 
I$Read 
I$ReadLn 
I$Seek 
I$SetStt 
I$Write 
I$WritLn 


8-4 


Sends a signal to a process 
Suspends a process 

Sets a process’s priority 

Sets a software interrupt vector 
Sets the system time 

Sets the user ID number 
Returns the current time 
Unlinks a module 

Unlinks a module by name 
Waits for a signal 

Attaches an I/O device 

Changes a working directory 
Closes a path 

Creates a new file 

Deletes a file 

Deletes a file from the execution directory 
Detaches an I/O device 
Duplicates a path 

Gets a device’s status 

Creates a directory file 

Opens a path to an existing file 
Reads data from a device 

Reads a line of data from a device 
Positions a file pointer 

Sets a device’s status 

Writes data to a device 


Writes a data line to a device 
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System Mode Calls Quick Reference 


Following is a summary of the System Mode Calls referenced in 


this chapter: 
F$Alarm 
FSAI164 


FSANHRAM 


F$AllImg 
FS$AIIPre 
FSAILRAM 
FSAITsk 
F$AProc 
FS$Boot 
F$BtMem 
F$ClrBlk 
FS$DATLog 


F$Dellmg 
F$DelPre 
F$DelRAM 
F$DelTsk 
F$ELink 


FSF Modul 
F$Find64 
F$FreeHB 
F$FreeLB 
F$GCMDir 
F$GProcP 


Sets up an alarm 

Allocates a 64-byte memory block 
Allocates high RAM 

Allocates image RAM blocks 
Allocates a process descriptor 
Allocates RAM blocks 

Allocates a process task number 
Enters active process queue 
Performs a system bootstrap 
Performs a memory request bootstrap 
Clears the specified block of memory 


Converts a DAT block offset to a logical 
address 


Deallocates image RAM blocks 
Deallocates a process descriptor 
Deallocates RAM blocks 
Deallocates a process task number 


Links modules using a module directory 
entry 


Finds a module directory entry 
Finds a 64-byte memory block 
Gets a free high block 

Gets a free low block 

Compacts module directory entries 


Gets a process’s pointer 
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F$IODel 
FSIOQu 
FSIRQ 
FSLDABX 
FSLDAXY 
FSLDDDXY 
F$MapBlk 
F$Move 
F$NProc 
FS$RelTsk 
F$ResTsk 
F$Ret64 
F$SetImg 
F$SetTsk 
F$SLink 
F$SRqMem 
FSSRtMem 
F$SSvec 
FSSTABX 
FSVIRQ 


F$V Modul 
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Deletes an I/O module 

Puts an entry into an I/O queue 
Makes an entry into IRQ polling table 
Loads Register A from 0,X in Task B 
Loads A[X,[Y]] 

Loads D[D + X,[Y]] 

Maps the specified block 

Moves data to a different address space 
Starts the next process 

Releases a task number 

Reserves a task number 

Returns a 64-byte memory block 

Sets a process DAT image 

Sets a process’s task DAT registers 
Performs a system link 

Performs a system memory request 
Performs a system memory return 
Installs a function request 

Stores Register A at 0,x in Task B 


Makes an entry in a virtual IRQ polling 
table 


Validates a module 
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User System Calls 


Allocate Bits Sets bits in an 
OS9 F$AIIBit 103F 13 allocation bit map 


Entry Conditions: 


D =numeber of the first bit to set 
X = starting address of the allocation bit map 
Y = number of bits to set 


Error Output: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 


@ Bit numbers range from 0 to n-1, where n is the number of 
bits in the allocation bit map. 


@ Warning: Do not issue the Allocate Bits call with Register 
Y set to 0 (a bit count of 0). 
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Chain Loads and executes a 
OS9 F$Chain 103F 05 new primary module 


without creating a new 
process 


Entry Conditions: 


A 


B 
X 
Y 
U 


= language/type code 

= size of the data area (in pages); must be at least one 
page 

= address of the module name or filename 

= parameter area size (in bytes); defaults to zero if not 
specified 

= starting address of the parameter area 


Error Output: 


CC =carry set on error 


B 


= error code (if any) 


Additional Information: 
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Chain loads and executes a new primary module, but does 
not create a new process. A Chain system call is similar to 
a Fork followed by an Exit, but it has less processing over- 
head. Chain resets the calling process program and data 
memory areas and begins executing a new primary module. 
It does not affect open paths. This is a user mode system 
call. 


Warning: Make sure that the hardware stack pointer (Reg- 
ister SP) is located in the direct page before Chain exe- 
cutes. Otherwise the system might crash or return a 
suicide attempt error. This precaution also prevents a sui- 
cide in the event that the new module requires a smaller 
data area than that in use. Allow approximately 200 bytes 
of stack space for execution of the Chain system call. 


Chain performs the following steps: 


1. It causes OS-9 to unlink the process’s old primary 
module. 
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OS-9 parses the name string of the new process’s pri- 
mary module (the program that is to be executed first). 
Then, it causes OS-9 to search the system module 
directory to see if a module with the same name, type, 
and language is already in memory. 


If the module is in memory, it links to it. If the module 
is not in memory, it uses the name string as the path- 
list of a file to load into memory. Then, it links to the 
first module in this file. (Several modules can be loaded 
from a single file.) 


It reconfigures the data memory area to the size speci- 
fied in the new primary module’s header. 


It intercepts and erases any pending signals. 


The following diagram shows how Chain sets up the 
data memory area and registers for the new module. 


<+ Y (highest address) 


Parameter Area 
+ X,SP 


Data Area 


Direct Page 


+ U,DP (lowest address) 


= parameter area size 


module entry point absolute address 
F=0, I=0; others are undefined 


Registers Y and U (the top-of-memory and bottom-of-memory 
pointers, respectively) always have values at page boundaries. If 
the parent process does not specify a size for the parameter area, 
the size (Register D) defaults to zero. The data area must be at 
least one page long. 


(For more information, see the Fork system call.) 
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Compare Names Compares two strings 
OS9 F$CmpNam 103F 11 =F 2 Match 


Entry Conditions: 
B- = length of string1 
X = address of string! 
Y = address of string2 
Exit Conditions: 


CC =carry clear if the strings match 


Additional Information: 


@ The Compare Names call compares two strings and indi- 
cates whether they match. Use this call with the Parse 
Name system call. The second string must have the most 
significant bit (Bit 7) of the last character set. 
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Copy External Reads external memory 


; into the user’s buffer 
Memory for inspection 
OS9 F$CpyMem 
103F 1B 


Entry Conditions: 


= DAT image pointer 

= offset in block to begin copy 
byte count 

= caller’s destination buffer 


qk Ko 
] 


Error Output: 


CC =C bit set on error 
B = appropriate error code 


Additional Information: 


@ You can view any system memory through the use of the 
Copy External Memory call. The call assumes X is the 
address of the 64K space described by the DAT image 
given. 


@ If you pass the entire DAT image of a process, place a value 
in the X Register that equals the address in the process 
space. If you pass a partial DAT image (the upper half), 
then place a value in Register X that equals the offset from 
the beginning of the DAT image ($8000). 


@ The support module for this call is OS9p2. 
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CRC Calculates the CRC of 
OS9 F$CRC 103F 17 a module 


Entry Conditions: 


X = starting byte address 
Y  =numeber of bytes 
U = address of the 3-byte CRC accumulator 


Exit Conditions: 
Updates the CRC accumulator. 


Additional Information: 


@ The CRC call calculates the CRC (cyclic redundancy count) 
for use by compilers, assemblers, or other module 
generators. 


@ The calculation begins at the starting byte address and con- 
tinues over the specified number of bytes. 


@ You need not cover an entire module in one call, since the 
CRC can be accumulated over several calls. The CRC accu- 
mulator can be any 3-byte memory area. You must initial- 
ize it to $FFFFFF before the first CRC call. 


@ When checking an existing module CRC, the calculation 
should be performed on the entire module (including the 
module CRC). The CRC accumulator will contain the CRC 
constant bytes if the module CRC is correct. 


e If the CRC of a new module is to be generated, the CRC is 
accumulated over the module (excluding CRC). The accu- 
mulated CRC is complemented then stored in the correct 
position in the module. 


@ Be sure to initialize the CRC accumulator only once for 
each module checked by CRC. 


8-12 


User System Calls / 8 


Deallocate Bits Clears allocation map 
OS9 F$DelBit 103F 14 pits 


Entry Conditions: 


D =number of the first bit to set 
X = starting address of the allocation bit map 
Y = number of bits to set 


Exit Conditions: None 


Additional Information: 


@ The Deallocate Bits call clears bits in the allocation bit 
map pointed to by Register X. Bit numbers are in the 
range 0 to n-1, where n is the number of bits in the alloca- 
tion bit map. 


@ Warning: Do not call Deallocate Bits with Register Y set 
to 0 (a bit count of 0). 
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Exit Terminates the calling 
OS9 F$SExit 103F 06 process 


Entry Conditions: 


B 


= status code to return to the parent 


Exit Conditions: 


The process is terminated. 


Additional Information: 
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The Exit system call is the only way a process can termi- 
nate itself. Exit deallocates the process’s data memory 
area, and unlinks the process’s primary module. It also 
closes all open paths automatically. 


The Wait system call always returns to the parent the sta- 
tus code passed by the child in its Exit call. Therefore, if 
the parent executes a Wait and receives the status code, it 
knows the child has died. This is a user mode system call. 


Exit unlinks only the primary module. Unlink any module 
that is loaded or linked to by the process before calling 
Exit. 
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Fork Creates a child process 
OS9 F$Fork 103F 03 


Entry Conditions: 


A = language/type code 

B = size of the optional data area (in pages) 

X = address of the module name or filename (See the follow- 
ing example.) 

Y = size of the parameter area (in pages); defaults to zero if 
not specified 

U = starting address of the parameter area; must be at 
least one page 


Exit Conditions: 


X  =address of the last byte of the name + 1 (See the fol- 
lowing example.) 
A = new process IO number 


Error Output: 
B = error code (if any) 
CC =carry set on error 


Additional Information: 


@ Fork creates a new process, a child of the calling process. 
Fork also sets up the child process’s memory and 6809 reg- 
isters and standard I/O paths. 


@ Before the Fork call: 


TLE} S| T| sop 


4 
Xx 
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e After the Fork call: 
4 


xX 
@ This is the sequence of Fork’s operations: 


1. OS-9 parses the name string of the new process’s pri- 
mary module (the program that OS-9 executes first). 
Then, it searches the system module directory to see if 
the program already is in memory. 


2a. The next step depends on whether or not the program is 
already in memory. If the program is in memory, OS-9 
links the module to the process and executes it. 


b. If the program is not in memory, OS-9 uses the name 
as the pathlist of the file that is to be loaded into mem- 
ory. Then, the first module in this file is linked to and 
executed. (Several modules can be loaded from one file.) 


3. OS-9 uses the primary module’s header to determine 
the initial size of the process’s data area. It then tries 
to allocate a contiguous RAM area of that size. (This 
area includes the parameter passing area, which is cop- 
ied from the parent process’s data area.) 


4. The new process’s data memory area and registers are 
set up as shown in the following diagram. OS-9 uses 
the execution offset given in the module header to set 
the program counter to the module’s entry point. 


Parameter Area 


+ Y 
«+ X,SP (highest address) 


Data Area 


Direct Page 


U,DP (lowest address) 
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D- = size of the parameter area 
PC = module entry point absolute address 
CC = F=0, I=0, other condition code flags are undefined 


Registers Y and U (the top-of-memory pointer and bottom- 
of-memory pointer, respectively) always have values at page 
boundaries. 


As stated earlier, if the parent does not specify the size of 
the parameter area, the size defaults to zero. The minimum 
overall data area size is one page. 


When the shell processes a command line, it passes a 
string in the parameter area. This string is a copy of the 
parameter part of the command line. To simplify string- 
oriented processing, the shell also inserts an end-of-line 
character at the end of the parameter string. 


Register X points to the start byte of the parameter string. 
If the command line includes the optional memory size 
specification (#n or #nK), the shell passes that size as the 
requested memory size when executing the Fork. 


If any of the preceding operations is unsuccessful, the Fork 
is terminated and OS-9 returns an error to the caller. 


The child and parent processes execute at the same time 
unless the parent executes a Wait system call immediately 
after the Fork. In this case, the parent waits until the child 
dies before it resumes execution. | 


Be careful when recursively calling a program that uses 
the Fork system call. Another child can be created with 
each new execution. This continues until the process table 
becomes full. 


Do not fork a process with a memory size of 0. 
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Get System Gets a copy of the 
Blo ek Map system block map 
OS9 F$GBIkMp 103F 19 ~ 


Entry Conditions: 
X = pointer to the 1024-byte buffer 


Exit Conditions: 


D =number of bytes per block ($2000) (MMU block size 
dependent) 
Y = system memory block map size 


Error Output: 


CC =carry set on error 
B = error code (if any) 
Additional Information: VY 


@ The Get System Block Map call copies the system’s memory 
block map into the user’s buffer for inspection. The OS-9 
MFREE command uses this call to find out how much free 
memory exists. 


@ The support module for this call is OS9p2. 
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Get Module Gets a copy of the 
Director system module 
y directory 


F$GModDr 103F 1A 


Entry Conditions: 

X = pointer to the 2048-byte buffer 

Y = end of copied module directory 

U = start address of system module directory 
Error Output: 

CC =carry set on error 

B = error code (if any) 
Additional Information: 


@ The Get Module Directory call copies the system’s module 
directory into the user’s buffer for inspection. The OS-9 
MDIR command uses this call to read the module 
directory. 


@ The support module for this call is OS9p2. 
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Get Process Gets a copy of the 
Descr1 tor process’s process 
P descriptor 


F$GPrDsc 103F 18 


Entry Conditions: 

A = requested process ID 

xX = pointer to a 512-byte buffer 
Error Output: 

CC =carry set on error 

B = error code (if any) 
Additional Information: 


@ The Get Process Descriptor call copies a process descriptor 
into the calling process’s buffer for inspection. The data in 
the process descriptor cannot be changed. The OS-9 PROCS 
command uses this call to get information about each exist- 
ing process. 


e@ The support module for this call is OS9pz2. 


8-20 


User System Calls / 8 


Intercept Sets a signal intercept 
OS9 F$Icpt 103F 09 ep 


Entry Conditions: 
X = address of the intercept routine 
U = starting address of the routine’s memory area 
Exit Conditions: 
Signals sent to the process cause the intercept routine to be 
called instead of the process being killed. 
Additional Information: 


@ Intercept tells OS-9 to set a signal intercept trap. Then, 
whenever the process receives a signal, OS-9 executes the 
process’s intercept routine. 


@ Store the address of the signal handler routine in Register 
X and the base address of the routine’s storage area in 
Register U. 


@ Once the signal trap is set, OS-9 can execute the intercept 
routine at any time because a signal can occur at any 
time. 


e@ Terminate the intercept routine with an RTI instruction. 


e Ifa process has not used the Intercept system call to set a 
signal trap, the process terminates if it receives a signal. 


@ This is the order in which F$lIcpt operates: 


1. When the process receives a signal, OS-9 sets Registers 
U and B as follows: 


U_ = starting address of the intercept routine’s 
memory area 
B- = signal code (process’s termination status) 


Note: The value of Register DP cannot be the 
same as it was when the Intercept call was 
made. 


2. After setting the registers, OS-9 transfers execution to 
the intercept routine. 
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Get ID Return’s a caller’s 
OS9 FSID 103F 0C process ID and user ID 


Entry Conditions: 


None 


Exit Conditions: 


A = process ID 
bf = user ID 


Additional Information: 


@ The process ID is a byte value in the range 1 to 255. OS-9 
assigns each process a unique process ID. 


@ The user ID is an integer from 0 to 65535. It is defined in 
the system password file, and is used by the file security 
system and a few other functions. Several processes can 
have the same user ID. 


@ On a single user system (such as the Color Computer 3), 
the user ID is inherited from CC3go, which forks the initial 
shell. 
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Link Links to a memory 
module that has the 

OS9 F$Link 103F 00 specified name, 

language, and type 


Entry Conditions: 


A = type/language byte 
X =address of the module name (See the following 
example.) 


Exit Conditions: 


A = type/language code 

B= attributes / revision level (if no error) 

X = address of the last byte of the module name + 1 (See 
the following example.) 

Y = module entry point absolute address 

U = module header absolute address 


Error Output: 


CC =C bit set if error encountered 


Additional Information: 


@ The module’s link count increases by one whenever Link 
references its name. Incrementing in this manner keeps 
track of how many processes are using the module. 


e If the module requested is not shareable (not re-entrant), 
only one process can link to it at a time. 


@ Before the Link call: 


N 
Xx 


@ After the Link call: 


4 
Xx 
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@ This is the order in which the Link call operates: 


1. OS-9 searches the module directory for a module that 
has the specified name, language, and type. 


2. If OS-9 finds the module, the address of the module’s 
header is returned in Register U, and the absolute 
address of the module’s execution entry point is 
returned in Register Y. (This, and other information is 
contained in the module header.) 


e If OS-9 doesn’t find the module—or if the type/language 
codes in the entry and exit conditions don’t match—OS-9 
returns one of the following errors: 


¢ Module not found 
¢ Module busy (not shareable and in use) 
¢ Incorrect or defective module header 
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Load Loads a module or 
OS9 F$Load 103F 01 modules from a file 


Entry Conditions: 


A = language/type code; 0 = any language/type 
X  =address of the pathlist (filename) (See the following 
example.) 


Exit Conditions: 


A = language/type code 

B = attributes / revision level (if no error) 

X = address of the last byte of the pathlist (filename) + 1 
(See the following example.) 

Y = primary module entry point address 

U = address of the module header 


Error Output: 


CC =carry set if error encountered 


Additional Information: 


@ The Load call loads one or more modules from the file spec- 
ified by a complete pathlist or from the working execution 
directory (if an incomplete pathlist is given). 


@ The file must have the execute access mode bit set. It also 
must contain one or more with proper module headers. 


@ OS-9 adds all modules loaded to the system module direc- 
tory. It links the first module read. The exit conditions 
apply only to the first module loaded. 


® Before the Load call: 
|‘ [p]o]/jalcic[r[s[R] cv sop] 
4 


Xx 
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After the Load call: 


(i {[plol/falc|ce|t|s{R|c} Vv sop | 
N 


WO 
X 
@ Possible errors: 
¢ Module directory full 
¢ Memory full 
¢ Errors that occur on the Open, Read, Close, and Link 
system calls 
UW 
Ww 
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Memory Changes process’s data 
OS9 F$Mem area size 
103F 07 


Entry Conditions: 
D = size of the new memory area (in bytes); 
0 = return current size and upper bound 
Exit Conditions: 
Y = address of the new memory area upper bound 
D = actual size of the new memory (in bytes) 
Error Output: 


CC 
B 


carry set on error 
error code (if any) 


Additional Information: 


@ The memory call expands or contracts the process’s data 
memory area to the specified size. Or, if you specify zero as 
the new size, the call returns the current size and upper 
boundaries of data memory. 


@ OS-9 rounds off the size to the next page boundary. In allo- 
cating additional memory, OS-9 continues upward from the 
previous highest address. In deallocating unneeded mem- 
ory, it continues downward from that address. 
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Link to a module Links to a module; 


OS9 F$NMLink does not map the 
103F 21 module into the user’s 


address space 


Entry Conditions: 


A = type/language byte 
X = address of the module name 


Exit Conditions: 


A = type/language code 

B = module revision 

X  =address of the last byte of the module name+1; any 
trailing blanks are skipped 

Y = storage requirement for the module 


Error Output: 


CC  =carry set on error 
B = error code if any 


Additional Information: 


e Although this call is similar to F$Link, it does not map 
the specified module into the user’s address space but does 
return the memory requirement for the module. A calling 
process can use this memory requirement information to 
fork a program with a maximum amount of space. 
F$NMLink can therefore fork larger programs than can be 
forked by F$Link. 
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Load a module Loads one or more 

OS9 F$SNMLoad modules from a file but 
: does not map the 

103F 22 : ; 

module into the user’s 

address space 


Entry Conditions: 


A = type/language byte 
X = address of the pathlist 


Exit Conditions: 


A = type/language code 

B = module revision 

X = address of the last byte of the pathlist+1 
Y = storage requirement for the module 


Error Output: 


CC =carry set on error 
B = error code if any 


Additional Information: 


@ If you do not provide a full pathlist for this call, it attempts 
to load from a file in the current execution directory. 


e Although this call is similar to F$Load, it does not map 
the specified module into the user’s address space but does 
return the memory requirement for the module. A calling 
process can use this memory requirement information to 
fork a program with a maximum amount of space. 
F$NMLoad can therefore fork larger programs than can be 
forked by F$Load. 
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Print Error Writes an error 
OS9 F$Perr 103F OF message to a specified 
path 


Entry Conditions: 


B = error code 


Error Output: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 


e Print Error writes an error message to the standard error 
path for the specified process. By default, OS-9 shows: 


ERROR #decimal number 


@ The error reporting routine is vectored. Using the Set SVC 
system call, you can replace it with a more elaborate 
reporting module. 
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Parse Name Scans an input string 
OS9 F$PrsNam 103F 10 for a valid OS-9 name 


Entry Conditions: 
X = address of the pathlist (See the following example.) 


Exit Conditions: 
X = address of the optional slash + 1 


Y = address of the last character of the name +1 
A = trailing byte (delimiter character) 
B- = length of the name 


Error Output: 
CC =carry set 


B = error code 
Y  =address of the first non-delimiter character in the 
string 


Additional Information: 


e Parses, or scans, the input text string for a legal OS-9 
name. It terminates the name with any character that is 
not a legal name character. 


@ Parse Name is useful for processing pathlist arguments 
passed to new processes. 


® Because Parse Name processes only one name, you might 
need several calls to process a pathlist that has more than 
one name. As you can see from the following example, 
Parse Name finishes with Register Y in position for the 
next parse. 


e If Register Y was at the end of a pathlist, Parse Name 
returns a bad name error. It then moves the pointer in Reg- 
ister Y past any space characters so that it can parse the 
next pathlist in a command line. 
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@ Before the Parse Name call: 


/{Dlo}/ | PlAlY [R{OjL/ Lb |» |b | 
4 
X 


After the Parse Name call: 
/{D]o|/|PJAlY |RJO/LILI| 4] be | 
4 4 BS 2 


X x 
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Search Bits Searches a specified 


memory allocation bit 
OS9 F$SchBit 103F 12 map for a free memory 
block of a specified 


size 


Entry Conditions: 


D- = starting bit number 

X = starting address of the map 
Y = bit count (free bit block size) 
U = ending address of the map 


Error Output: 
CC =C bit set 


Exit Conditions: 


D  =starting bit number 
Y = bit count 


Additional Information: 


@ The Search Bit call searches the specified allocation bit 
map for a free block (cleared bits) of the required length. 
The search starts at the starting bit number. If no block of 
the specified size exists, the call returns with the carry set, 
starting bit number, and size of the largest block. 
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Send Sends a signal to a 
OS9 F$Send 103F 08 specified process 


Entry Conditions: 


A 
B 


= destination’s process ID 
= signal code 


Error Output: 


CC 


B 


carry set on error 
error code (if any) 


Additional Information: 
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The signal code is a single byte value in the range 0 
through 255. 


If the destination process is sleeping or waiting, OS-9 acti- 
vates the process so that the process can process the signal. 


If a signal trap is set up, F$Send executes the signal pro- 
cessing routine (Intercept). If none was set up, the signal 
terminates the destination process, and the signal code 
becomes the exit status. (See the Wait system call.) An 
exception is the wakeup signal; that signal does not cause 
the signal intercept routine to be executed. 


Signal codes are defined as follows: 


0 = System terminate 
(cannot be intercepted) 
1 = Wake up the process 
2 = Keyboard terminate 
3 = Keyboard interrupt 
128-255 = User defined 


If you try to send a signal to a process that has a signal 
pending, OS-9 cancels the current Send call, and returns 
an error. Issue a Sleep call for a few ticks; then, try again. 


The Sleep call saves CPU time. See the Intercept, Wait, 
and Sleep system calls for more information. 
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Sleep Temporarily turns off 


OS9 F$Sleep 103F 0A 


the calling process 


Entry Conditions: 


xX 


= One of the following: 
sleep time (in ticks) 
0 (sleep indefinitely) 
1 (sleep for the remainder of 
the current time slice) 


Exit Conditions: 


xX 


= sleep time minus the number of ticks that the process 
was asleep 


Error Output: 


CC 


B 


carry set on error 
error code (if any) 


Additional Information: 


If Register X contains 0, OS-9 turns the process off until it 
receives a signal. Putting a process to sleep is a good way 
to wait for a signal or interrupt without wasting CPU time. 


If Register X contains 1, OS-9 turns the process off for the 
remainder of the process’s current time slice. It inserts the 
process into the active process queue immediately. The pro- 
cess resumes execution when it reaches the front of the 
queue. 


If Register X contains an integer in the range 2-255, OS-9 
turns off the process for the specified number of ticks, n. It 
inserts the process into the active process queue after n-1 
ticks. The process resumes execution when it reaches the 
front of the queue. If the process receives a signal, it awak- 
ens before the time has elapsed. 


When you select processes among multiple windows, you 
might need to set sleep for two ticks. 
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Set Priority 


OS9 F$SPrior 103F 0D 


Entry Conditions: 
A = process ID 


B = priority 
0 = lowest 
255 = highest 
Error Output: 
CC =carry set on error 
B = error code (if any) 


Additional Information: 


Changes the priority 
of a process 


@ Set Priority changes the process’s priority to the priority 
specified. A process can change another process’s priority 


only if it has the same user ID. 
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Set SWI Sets the SWI2 and 


OS9 F$SSWI 103F 0E SWIS8 vectors 


Entry Conditions: 

A = SWI type code 

X = address of the user software interrupt routine 
Exit Conditions: 

CC =carry set on error 

B = error code (if any) 
Additional Information: 


® Sets the interrupt vectors for SWI, SWI2 and SWI3 
instructions. 


@ Each process has its own local vectors. Each Set SWI call 
sets one type of vector according to the code number passed 
in Register A: 


1 = SWI 
2 = SWI2 
3 = SWI3 


@ When OS-9 creates a process, it initializes all three vectors 
with the address of the OS-9 service call processor. 


@ Warning: Microware-supplied software uses SWI2 to call 
OS-9. If you reset this vector, these programs cannot work. 
If you change all three vectors, you cannot call OS-9 at all. 
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Set Time Sets the system time 
OS9 F$STime 103F 16 ne Date 
Entry Conditions: 

X = relative address of the time packet 


Error Output: 


CC. = C bit set 
B = error code 


Additional Information: 


e Set Time sets the current system date and time and starts 
the system real-time clock. The date and time are passed 
in a time packet as follows. 


Relative 
Address Value 
0 year 
1 month 
z day 
3 hours 
4 minutes 
5 seconds 


Then, the call makes a link system call to find the clock. If 
the link is successful, OS-9 calls the clock initialization. 
The clock initialization: 


1. Sets up hardware dependent functions 


2. Sets up the F$Time system call via F$SSvec 
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Set User ID Changes the current 
user ID without 

Number checking for errors or 

F$SUser 103F 1C checking the ID 


number of the caller 


Entry Conditions: 


Y = desired user ID number 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


e@ The support module for this call is OS9p1. 
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Time Gets the system date 
OS9 F$Time 103F 15 and time 


Entry Conditions: 
X = address of the area in which to store the date and time 
packet 
Exit Conditions: 
X = date and time 


Error Output: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 


@ The Time call returns the current system date and time in 
the form of a 6-byte packet (in binary). OS-9 copies the 
packet to the address passed in Register X. 


@ The packet looks like this: 


Relative 
Address Value 
0 year 
z month 
2 day 
3 hours 
4 minutes 
5 seconds 


@ Time is a part of the clock module and it does not exist if 
no previous call to F$Time has been made. 
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Unlink Unlinks (removes 
p from memory) a 
OS9 F$UnLink 103F 02 wodule thatisnc 
in use and that has 
a link count of 0 


Entry Conditions: 
U = address of the module header 


Error Output: 


CC = carry set on error 
B = error code (if any) 


Additional Information: 


@ Unlink unlinks a module from the current process’s 
address space, decreases its link count by one and, if the 
link count becomes zero, returns the memory where the 
module was located to the system for use by other 
processes. 


@ You cannot unlink system modules or device drivers that 
are in use. 


@ Unlink operates in the following order: 


1. Unlink tells OS-9 that the calling process no longer 
needs the module. 


2. OS-9 decreases the module’s link count by one. 


When the resulting link count is zero, OS-9 destroys 
the module. 


If any other process is using the module, the module’s 
link count cannot fall to zero. Therefore, OS-9 does not 
destroy the module. 


@ If you pass a bad address, Unlink cannot find a module in 
the module directory and does not return an error. 
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Unlink Decrements a specified 
module’s link count, 

A Module and removes the 

By Name module from memory if 
the resulting link count 


F$UnLoad 103F 1D ; 
is zero 
Entry Conditions: 


A 
Xx 


module type 
pointer to module name 


Error Output: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 


e This system call differs from Unlink in that it uses a 
pointer to the module name, instead of the address of the 
module header. 


@ The support module for this call is OS9pz2. 
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Wait Temporarily turns off a 
OS9 F$Wait 103F 04 calling process 


Entry Conditions: None 


Exit Conditions: 


A 
B 


= deceased child process’s ID 
= deceased child process’s exit status code (if no error) 


Error Output: 


CC =carry set on error 


B 


= error code if any 


Additional Information: 


The Wait call turns off the calling process until a child pro- 
cess dies, either by executing an Exit system call, or by 
receiving a signal. The Wait call helps you save system 
time. 


OS-9 returns the child’s process’s ID and exit status to the 
parent. If the child died because of a signal, the exit status 
byte (Register B) contains the signal code. 


If the caller has several children, OS-9 activates the caller 
when the first one dies. Therefore, you need to use one Wait 
system call to detect the termination of each child. 


OS-9 immediately reactivates the caller if a child dies 
before the Wait call. If the caller has no children, Wait 
returns an error. (See the Exit system call for more 
information. ) 


If the Wait call returns with the carry bit set, the Wait 
function was not successful. If the carry bit is cleared, Wait 
functioned normally and any error that occurred in the 
child process is returned in Register B. 
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I/O User System Calls 


Attach Attaches a device to 


the system or verifies 
OS9 I$Attach 103F 80 device attachment 


Entry Conditions: 


A = access mode 
X = address of the device name string 


Exit Conditions: 


X = updated past device name 
U —_ = address of the device table entry 


Error Output: 


B = error code (if any) 
CC =carry set on error 


Additional Information: 


e Attach does not reserve the device. It only prepares the 
device for later use by any process. 


@ OS-9 installs most devices automatically on startup. There- 
fore, you need to use Attach only when installing a device 
dynamically or when verifying the existence of a device. You 
need not use the Attach system call to perform routine I/O. 


e@ The access mode parameter specifies the read and/or write 
operations to be allowed. These are: 


Use any special device capabilities 
Read only 

Write only 

Update (read and write) 


0 
1 
2 
3 
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@ Attach operates in this sequence: 


1; 


2a. 


OS-9 searches the system module to see if memory con- 
tains a device descriptor that has the same name as the 
device. 


OS-9’s next operation depends on whether or not the 
device is already attached. If OS-9 finds the descriptor 
and if the device is not already attached, OS-9 links the 
device’s file manager and device driver. It then places 
the address of the manager and the driver in a new 
device table entry. OS-9 then allocates any memory 
needed by the device driver, and calls the driver’s ini- 
tialization routine which initializes the hardware. 


. If OS-9 finds the descriptor, and if the device is already 


attached, OS-9 verifies the attachment. 


OS-9 Technical Reference 


Change Directory Changes the working 
, directory of a process 
OS? I9Chgair Ish 20 to a directory specified 
by a pathlist 

Entry Conditions: 

A = access mode 

X = address of the pathlist 
Exit Conditions: 

X = updated past pathlist 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


e If the access mode is read, write, or update, OS-9 changes 
the current data directory. If the access mode is execute, 
OS-9 changes the current execution directory. 


e@ The calling process must have read access to the directory 
specified (public read if the directory is not owned by the 
calling process). 


@ The access modes are: 


Read 

Write 

Update (read and write) 
Execute 


1 
2 
3 
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Close Path Terminates an I/O path 
OS9 I$Close 103F 8F 


Entry Conditions: 


A 


= path number 


Error Output: 


CC =carry set on error 


B 


= error code (if any) 


Additional Information: 


Close Path terminates the I/O path to the file or device 
specified by path number. Until you use another Open, 
Dup, or Create system call for that path, you can no longer 
perform I/O to the file or device. 


If you close a path to a single-user device, the device 
becomes available to other requesting processes. OS-9 de- 
allocates internally managed buffers and descriptors. 


The Exit system call automatically closes all open paths. 
Therefore, you might not need to use the Close Path system 
call to close some paths. 


Do not close a standard I/O path unless you want to change 
the file or device to which it corresponds. 


Close Path performs an implied I$Detach call. If it causes 
the device link count to become 0, the device termination 
routine is executed. See I$Detach for additional 
information. 
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Create File Creates and opens a 
OS9 I$Create 103F 83 disk file 
Entry Conditions: 

A = access mode (write or update) 


B = file attributes 
X = address of the pathlist; (See the following example.) 


Exit Conditions: 


A = path number 
X  =address of the last byte of the pathlist + 1; skips any 
trailing blanks (See the following example.) 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ OS-9 parses the pathlist and enters the new filename in the 
specified directory. If you do not specify a directory, OS-9 
enters the new filename in the the working directory. 


@ OS-9 gives the file the attributes passed in Register B, 
which has bits defined as follows: 


Bit Definition 


Read 

Write 

Execute 
Public read 
Public write 
Public execute 
Shareable file 


@ The access mode parameter passed in Register A must have 
the write bit set if any data is to be written. These access 
codes are defined as follows: 2 = write; 3 = update. The 
mode affects the file only until the file is closed. 


OOP WNEF © 
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You can reopen the file in any access mode allowed by the 
file attributes. (See the Open system call.) 


Files opened for write can allow faster data transfer than 
those opened for update because update sometimes needs to 
pre-read sectors. 


If the execute bit (Bit 2) is set, the file is created in the 
working execution directory instead of the working data 
directory. 


Create File causes an implicit I$Attach call. If the device 
has not previously been attached, the device’s initialization 
routine is called. 


Later I/O calls use the path number to identify the file, 
until the file is closed. 


OS-9 does not allocate data storage for a file at creation. 
Instead, it allocates the storage either automatically when 
you first issue a write or explicitly by the Setstat 
subroutine. 


If the filename already exists in the directory, an error 
occurs. If the call specifies a non-multiple file device (such 
as a printer or terminal), Create behaves the same as 
Open. 


You cannot use Create to make directories. (See the Make 
Directory system call for instructions on how to do make 
directories. ) 


Before the Create File call: 


|/ | Dd] o}/|wlo/R|K| sop | 


4 
X 


After the Create File call: 
/|pjo}/{|wlo] RK | sop | 


N 
X 
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Delete File Deletes a specified disk 
OS9 I$Delete 103F 87 file 


Entry Conditions: 
X = address of the pathlist (See the following example.) 


Exit Conditions: 


X  =address of the last byte of the pathlist + 1; any trail- 
ing blanks are skipped (See the following example.) 


Error Output: 


B = error code (if any) 
CC =carry set on error 


Additional Information: 


@ The Delete File call deletes the disk file specified by the 
pathlist. The file must have write permission attributes | 
(public write, if the calling process is not the owner). An ~ 
attempt to delete a device results in an error. The caller 
must have non-shareable write access to the file or an error 
results. 


Example: 
Before the Delete File call: 
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Delete A File Deletes a file from the 


OS9 I$DeletX 103F 90 current data or current 
execution directory 


Entry Conditions: 
A = access mode 
X = address of the pathlist 
Exit Conditions: 
X = address of the last byte of the pathlist+1; any trailing 
blanks are skipped 
Error Output: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 


@ The Delete A File call removes the disk file specified by the 
selected pathlist. This function is similar to I$Delete except 
that it accepts an access mode byte. If the access mode is 
execute, the call selects the current execution directory. 
Otherwise, it selects the current data directory. 


@ If a complete pathlist is provided (the pathlist begins with 
a slash (/), the access mode the call ignores the access 
mode. 


@ Only use this call to delete a file. If you attempt to use 
I$DeletX to delete a device, the system returns an error. 
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Detach Device Removes a device 


from the system 
OS9 I$Detach 103F 81 device table 


Entry Conditions: 
U = address of the device table entry 


Exit Conditions: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


® The Detach Device call removes a device from both the sys- 
tem and the system device table, assuming the device is not 
being used by another process. You must use this call to 
detach devices attached using the Attach system call. 
Attach and Detach are both used mainly by the IO man- 
ager. SCF also uses Attach and Detach to set up its second 
device (echo device). 


@ This is the sequence of the operation of Detach Device: 


1. Detach Device calls the device driver’s termination rou- 
tine. Then, OS-9 deallocates any memory assigned to 
the driver. 


2. QOS-9 unlinks the associated device driver and file man- 
ager modules. 


3. OS-9 then removes the driver, as long as no other mod- 
ule is using that driver. 
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D uplic ate Path Returns a synonymous 
OS9 I$Dup 103F 82 path number 


Entry Conditions: 
A = old path number (number of path to duplicate) 


Exit Conditions: 


A = new path number (if no error) 


Error Output: 


B = error code (if error encountered) 
CC =carry set on error 


Additional Information: 


@ The Duplicate Path returns another, synonymous path 
number for the file or device specified by the old path 
number. 


@ The shell uses the Duplicate Path call when it redirects 
L/O. 


@ System calls can use either path number (old or new) to 
operate on the same file or device. 


@ Make sure that no more than one process is performing I/O 
on any one path at the same time. Concurrent I/O on the 
same path can cause unpredictable results with RBF files. 


@ The I$Dup call always uses the lowest available path num- 
ber. This lets you manipulate standard I/O paths to contain 
any desired paths. 
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Get Status Returns the status of a 
OS9 I$GetStt 103F 8D file or device 


Entry Conditions: 

A = path number 

B = function code 
Error Output: 

CC =carry set on error 

B = error code (if any) 
Additional Information: 


@® The Status is a wildcard call. Use it to handle device 
parameters that: 


¢ Are not the same for all devices 
« Are highly hardware-dependent 
¢ Must be user-changeable 


@® The exact operation of the Get Status system call depends 
on the device driver and file manager associated with the 
path. A typical use is to determine a terminal’s parameters 
for such functions as backspace character and echo on/off. 
The Get Status call is commonly used with the Set Status 
call. 


@ The Get Status function codes that are currently defined 
are listed in the “Get Status System Calls” section. 
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Make Directory Creates and initializes 
OS9 I$MakDir 103F 85 a directory 


Entry Conditions: 
B = directory attributes 
X = address of the pathlist 
Exit Conditions: 
X = address of the last byte of the pathlist +1; Make Direc- 
tory skips trailing blanks. 
Error Output: 
B = error code (if any) 
CC =carry set on error 
Additional Information: 


@ The Make Directory call creates and initializes a directory 
as specified by the pathlist. The directory contains only two 
entries, one for itself (.) and one for its parent directory (..) 


@ OS-9 makes the calling process the owner of the directory. 


@ Because the Make Directory call does not open the direc- 
tory, it does not return a path number. 


@ The new directory automatically has its directory bit set in 
the access permission attributes. The remaining attributes 
are specified by the byte passed in Register B. The bits are 
defined as follows: 


ee 
et 


Definition 
Read 

Write 
Execute 
Public read 
Public write 
Public execute 
Single-user 
Don’t care 


IH OP CONF © 
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@ Before the Make Directory call: 


(7 [pjto[/ [ne [wp] 1[R| sop_ 


4 
X 


After the Make Directory call: 
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Open Path Opens a path to an 

existing file or device 
OS9 1$Open 103F 84 as specified by the 
pathlist 


Entry Conditions: 


A  =access mode (D S PE PW PRE W R) 
X = address of the pathlist (See the following example.) 


Exit Conditions: 


A = path number 
X = address of the last byte of the pathlist + 1 


Error Output: 


B = error code (if any) 
CC =carry set on error 


Additional Information: 
@ OS-9 searches for the file in one of the following: 


¢ The directory specified by the pathlist if the pathlist 
begins with a slash. 


¢ The working data directory, if the pathlist does not 
begin with a slash. 


¢ The working execution directory, if the pathlist does not 
begin with a slash and if the execution bit is set in the 
access mode. 


@ OS-9 returns a path number for later system calls to use to 
identify the file. 


@ The access mode parameter lets you specify which read 
and/or write operations are to be permitted. When set, each 
access mode bit enables one of the following: Write, Read, 
Read and Write, Update, Directory I/O. 


@ The access mode must conform to the access permission 
attributes associated with the file or device. (See the Cre- 
ate system call.) Only the owner can access a file unless 
the appropriate public permission bits are set. 
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@ The update mode might be slightly slower than the others 
because it might require pre-reading of sectors for random 
access of bytes within sectors. 


@ Several processes (users) can open files at the same time. 
Each device has an attribute that specifies whether or not 
it is shareable. 


@ Before the Open Path call: 
/|Diol/jale|{c|r{s|P/a]¥| sop 
4 


X 
After the Open Path call: 


/{pio|/{alce|c|t{s|Plaly] sop 
N 


X 


e@ If the single-user bit is set, the file is opened for single-user 
access regardless of the settings of the file’s permission 


bits. WwW 
@ You must open directory files for read or write if the direc- 
tory bit (Bit 7) is set in the access mode. 


@ Open Path always uses the lowest path number available 
for the process. 
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Read Reads n bytes from a 
OS9 I$Read 103F 89 specified path 


Entry Conditions: 


A 
bs 
X 


= path number 
= number of bytes to read 
= address in which to store the data 


Exit Conditions: 


ba 


= number of bytes read 


Error Output: 


B 


= error code (if any) 


CC =carry set on error 


Additional Information: 


The Read call reads the specified number of bytes from the 
specified path. It returns the data exactly as read from the 
file/device, without additional processing or editing. The 
path must be opened in the read or update mode. 


If there is not enough data in the specified file to satisfy 
the read request, the call reads fewer bytes than requested 
but an end-of-file error is not returned. After all data in a 
file is read, the next I$Read call returns an end-of-file 
error. 


If the specified file is open for update, the record read is 
locked out on RBF-type devices. 


The keyboard terminate, keyboard interrupt, and end-of-file 
characters are filtered out of the Entry Conditions data on 
SCF-type devices unless the corresponding entries in the 
path descriptor have been set to zero. You might want to 
modify the device descriptor so that these values are ini- 
tialized to zero when the path is opened. 
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@ The call reads the number of bytes requested unless Read 
encounters any of the following: 


¢ An end-of-file character 
¢ An end-of-record character (SCF only) 


e An error 
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Read Line With Reads a text line with 
Editing editing 


OS9 I$ReadLn 103F 8B 


Entry Conditions: 


A = path number 
X = address at which to store data 
Y = maximum number of bytes to read 


Exit Conditions: 


Y  =number of bytes read 


Error Output: 


B = error code (if any) 
CC =carry set on error 


Additional Information: 


@ Read Line is similar to Read. The difference is that Read 
Line reads the input file or device until it encounters a car- 
riage return character or until it reaches the maximum 
byte count specified, whichever comes first. The Read Line 
also automatically activates line editing on character ori- 
ented devices, such as terminals and printers. The line 
editing refers to auto line feed, null padding at the end of 
the line, backspacing, line deleting, and so on. 


@ SCF requires that the last byte entered be an end-of-record 
character (usually a carriage return). If more data is 
entered than the maximum specified, Read Line does not 
accept it and a PD.OVF character (usually a bell) is 
echoed. 


@ After one Read Line call reads all data in a file, the next 
Read Line call generates an end-of-file error. 


@ (For more information about line editing, see “SCF Line 
Editing Functions” in Chapter 6.) 
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Seek Repositions a file 
OS9 I$Seek 103F 88 pointer 


Entry Conditions: 


A 
Xx 
U 


= path number 
= MS 16 bits of the desired file position 
= LS 16 bits of the desired file position 


Error Output: 


CC =carry set on error 


B 


= error code (if any) 


Additional Information: 
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The Seek Call repositions the path’s logical file pointer, the 
32-bit address of the next byte in the file to be read from or 
written to. 


You can perform a seek to any value, regardless of the file’s 
size. Later writes automatically expand the file to the 
required size (if possible). Later reads, however, return an 
end-of-file condition. Note that a seek to Address 0 is the 
same as a rewind operation. 


OS-9 usually ignores seeks to non-random access devices, 
and returns without error. 


On RBF devices, seeking to a new disk sector causes the 
internal disk buffer to be rewritten to disk if it has been 
modified. Seek does not change the state of record locking. 
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Set Status Sets the status of a file 
OS9 I$SetStt 103F 8E or device 


Entry Conditions: 


A = path number 

B = function code 

Other registers depend on the function code. 
Error Output: 


B = error code (if any) 

CC =carry set on error 

Other registers depend on the function code. 
Additional Information: 


@ Set Status is a wildcard call. Use it to handle device 
parameters that: 


¢ Are not the same for all devices 
¢ Are highly hardware-dependent 
¢ Must be user-changeable 


@ The exact operation of the Set Status system call depends 
on the device driver and file manager associated with the 
path. A typical use is to set a terminal’s parameters for 
such functions as backspace character and echo on/off. The 
Set Status call is commonly used with the Get Status call. 


@ The Set Status function codes that are currently defined 
are listed in the “Set Status System Calls” section. 
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Write Writes to a file or 
OS9 I$Write 103F 8A device 


Entry Conditions: 


A = path number 
X = starting address of data to write 
Y = number of bytes to write 


Exit Conditions: 


Y = number of bytes written 


Error Output: 


B = error code (if any) 
CC =carry set on error 


Additional Information: 


@ The Write system call writes to the file or device associated 
with the path number specified. 


® Before using Write, be sure the path is opened or created 
in the Write or Update access mode. OS-9 writes data to 
the file or device without processing or editing the data. 
OS-9 automatically expands the file if you write data past 
the present end-of-file. 
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Write Line Writes to a file or 
‘ device until it 
OS9 I$WritLn 103F 8C encounters a carriage 
return 


Entry Conditions: 


A = path number 
X = address of the data to write 
Y = maximum number of bytes to write 


Exit Conditions: 


Y = number of bytes written 


Error Output: 


B = error code (if any) 
CC =carry set on error 


Additional Information: 


@ Writes to the file or device that is associated with the path 
number specified. 


@ Write Line is similar to Write. The difference is that Write 
Line writes data until it encounters a carriage return char- 
acter. It also activates line editing for character-oriented 
devices, such as terminals and printers. The line editing 
refers to auto line feed, null padding at the end of the line, 
backspacing, line deleting, and so on. 


@ Before using Write Line, be sure the path is opened or cre- 
ated in the write or update access mode. 


@ (For more information about line editing, see “SCF Line 
Editing Functions” in Chapter 6.) 
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Privileged System Mode Calls 


Set an alarm Sets an alarm to ring 
OS9 F$Alarm 103F 1E wih ada eine 
ime 
Entry Conditions: 
X = relative address of time packet 


Error Output: 

CC =carry set on error 

B = appropriate error code 
Additional Information: 


@ When the system reaches the specified alarm time, it rings 
the bell for 15 seconds. 


e The time packet is identical to the packet used in the 
F$STime call. See F$STime for additional information on 
the format of the packet. 


e All alarms begin at the start of a minute and any seconds 
in the packet are ignored. 


@ The system is limited to one alarm at a time. 
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Allocate 64 Dynamically allocates 


OS9 F$All64 103F 30 64-byte blocks of 
memory 


Entry Conditions: 


X = base address of the page table; 0 = the page table has 
not been allocated 


Exit Conditions: 


A = block number 
X = base address of the page table 
Y  =address of the block 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ The Allocate 64 system call allocates the 64-byte blocks of 
memory by splitting pages (256-byte sections) into four 
sections. 


@ OS-9 uses the first 64 bytes of the base page as a page 
table. This table contains the page number (most signifi- 
cant byte of the address) of all pages in the memory struc- 
ture. If Register X passes a value of zero, the call allocates 
a new base page and the first 64-byte memory block. 


@ Whenever a new page is needed, a Request System Memory 
system call (F$SRqMem) executes automatically. 


@ The first byte of each block contains the block number. 
Routines that use the Allocate 64 call should not alter this 
byte. 
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@ The following diagram shows how seven blocks might be 


allocated: 


Base Page > 


Page Table 


(64 bytes) 


xX 
Block 1 
(64 bytes) 


».4 
Block 2 
(64 bytes) 


xX 
Block 3 
(64 bytes) 
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Any Memory Page 


4 
Block 4 
(64 bytes) 


X 


Block 5 
(64 bytes) 


xX 
Block 6 
(64 bytes) 


XxX 
Block 7 
(64 bytes) 
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Allocate High Allocate system 
RAM memory from high 


physical memory 
OS9 F$AlIHRam_ = 103F 53 


Entry Conditions: 
B = number of blocks 


Error Output: 

CC =carry set on error 

B = appropriate error code 
Additional Information: 


@ This call searches for the desired number of contiguous free 
RAM blocks, starting its search at the top of memory. 
F$AllHRam is similar to F$AlLRAM except F$AlIITRAM 
begins its search at the bottom of memory. 


@ Screen allocation routines use this call to provide a better 
chance of finding the necessary memory for a screen. 
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Allocate Image Allocates RAM 


blocks for process 
OS9 F$AllImg 103F 3A DAT image 


Entry Conditions: 


A = starting block number 
B = number of blocks 
X = process descriptor pointer 


Exit Conditions: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 


@ Use the Allocate Image system call to allocate a data area 
for a process. The blocks that Allocate Image defines might 
not be contiguous. 


e The support module for this system call is OS9p1. 
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Allocate Process Aliocates and 

initializes a 512-byte 
Descriptor process descriptor 
OS9 F$AllPre 103F 4B 


Entry Conditions: None 


Exit Conditions: 


U = process descriptor pointer 


Error Output: 


CC =C bit set on error 
B = appropriate error code 


Additional Information: 


@ The process descriptor table houses the address of the 
descriptor. Initialization of the process descriptor consists 
of clearing the first 256 bytes of the descriptor, setting up 
the state as a system state, and marking as unallocated as 
much of the DAT image as the system allows—typically, 
60-64 kilobytes. 


@ The support module for this system call is OS9p2. The call 
also branches to the F$SRqMem call. 
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Allocate RAM Searches the 
memory block map 

OS9 FSAIIRAM 103F 39 fe the desired 
number of 
contiguous free 
RAM blocks 


Entry Conditions: 
B = number of blocks 


Exit Conditions: 

CC =C bit set on error 

B = appropriate error code 
Additional Information: 


e The support module for this system call is OS9p1. 


Privileged System Mode Calls / 8 


Allocate Pp rOCe@SS Determines whether 


, OS-9 has assigned a 
Task Number task number to the 
OS9 F$AITsk 103F 3F specified process 


Entry Conditions: 


X = process descriptor pointer 


Error Output: 

CC =C bit set 

B = = appropriate error code 
Additional Information: 


@ If the process does not have a task number, OS-9 allocates 
a task number and copies the DAT image into the DAT 
hardware. 


@ The support module for this call is OS9p1. Allocate Process 
Task number also branches to F$ResTsk and F$SetT'sk. 
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Insert Process Inserts a process into 
OS9 F$AProc 103F 2C the queue for execution 


Entry Conditions: 
X = address of the process descriptor 


Error Output: 


CC 
B 


carry set on error 
error code (if any) 


Additional Information: 


@ The Insert Process system call inserts a process into the 
active process queue so that OS-9 can schedule the process 
for execution. 


e OS-9 sorts all processes in the queue by process age (the 
count of how many process switches have occurred since the 
process’s last time slice). When a process is moved to the 
active process queue, OS-9 sets its age according to its 
priority—the higher the priority, the higher the age. 


An exception is a newly active process that was deactivated 
while in the system state. OS-9 gives such a process higher 
priority because the process usually is executing critical 
routines that affect shared system resources. 
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Bootstrap System Links either the 
OS9 F$Boot 103F 35 module named Boot 
| or the module 
specified in the INIT 
module 


Entry Conditions: None 


Error Output: 

CC =C bit set on error 

B = appropriate error code 
Additional Information: 


@ When it calls the linked module, Boot expects to receive a 
pointer giving it the location and size of an area in which 
to search for the new module. 


@ The support module for this call is OS9p1. Bootstrap Sys- 
tem also branches to the F$Link and F$VModul system 
calls. 
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Bootstrap Allocates the 
requested memory 
Memory Request (a icd to the 
OS9 F$BtMem 103F 36 nearest block) as 
contiguous memory 
in the system’s 
address space 
Entry Conditions: 


D = byte count requested 


Exit Conditions: 
D- = byte count granted 
U = pointer to memory allocated 
Error Output: 
CC =C bit set on error 
B = _ = appropriate error code 
Additional Information: 
@ This call is identical to F$SRqMem. 
@ The Bootstrap Memory Request support module is OS9pl1. 
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Clear Specified Marks blocks in the 
Block process DAT image as 


unallocated 
OS9 F$ClrBlk 103F 50 


Entry Conditions: 

B = number of blocks 

U = address of first block 
Exit Conditions: None 


Additional Information: 


e@ After Clear Specified Block deallocates blocks, the blocks 
are free for the process to use for other data or program 
areas. If the block address passed to Clear Specified Block 
is invalid or if the call attempts to clear the stack area, it 
returns E$IBA. 


@ The support module for the call is OS9p2. 
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DAT to Logical Converts a DAT image 


clock number and 
Address block offset to its 
OS9 F$DATLog 103F 44 equivalent logical 
address 


Entry Conditions: 


B = DAT image offset 
X = = block offset 


Exit Conditions: 
X = logical address 


Error Output: 


CC =C bit set on error 
B = appropriate error code 


Additional Information: 


@ Following is a sample conversion: 


2000 - 2FFF 
1000 - 1FFF 
0 - FFF 


@ The support module for this call is OS9p1. 


Input: B = 2 
$0329 


Output: X = $2329 


8-78 


Privileged System Mode Calls / 8 


Deallocate Image Deallocates image 
R AM Blocks RAM blocks 


OS9 F$DelImg 103F 3B 


Entry Conditions: 


A = number of starting block 
B = block count 
X = process descriptor pointer 


Error Output: 
CC =C bit set on error 
B = appropriate error code 


Additional Information: 


@ This system call deallocates memory from a process’s 
address space. It frees the RAM for system use and frees 
the DAT image for the process. Its main use is to let the 
system clean up after a process death. 


@ The support module for this call is OS9p2. 
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Deallocate Returns a process 
Proce SS descriptor’s memory to 


‘ a free memory pool 
Descriptor 
OS9 F$DelPrc 103F 4C 


Entry Conditions: 


A = process ID 


Error Output: 

CC =C bit set on error 

B = appropriate error code 
Additional Information: 


@ Use this call to clear the system scratch memory and stack 
area associated with the process. 


e@ The support module for this call is OS9p2. 
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Deallocate RAM Clears a block’s RAM 
blocks In Use flag in the 


system memory block 
OS9 F$DelIRAM 103F 51 map 


Entry Conditions: 

B = number of blocks 

X = starting block number 
Exit Conditions: None 


Additional Information: 


@ The Deallocate RAM Blocks call assumes the blocks being 
deallocated are not associated with any DAT image. 


@ The support module for this call is OS9p2. 
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Deallocate Task Releases the task 


Numb er number that the 

process specified by WwW 
OS9 F$DelTsk 103F 40 the passed descriptor 

pointer 


Entry Conditions: 


X = process descriptor pointer 


Error Output: 


CC =C bit set on error 
B = appropriate error code 


Additional Information: 


@ The support module for this call is OS9p1. 
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Link Using Performs a link using a 
Module Directory pointer to a module 


directory entry 
Entry 
OS9 F$ELink 103F 4D 


Entry Conditions: 

B = module type 

X = pointer to module directory entry 
Exit Conditions: 

U = module header address 

Y = module entry point 
Error Output: 

CC =C bit set on error 

B = appropriate error code 
Additional Information: 


@ This call differs from Link in that you supply a pointer to 
the module directory entry rather than a pointer to a mod- 
ule name. 


@ The support module for this call is OS9p1. 
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Find Module Returns a pointer to 
Directory Entry the module directory 
OS9 F$FModul 103F 4E 


entry 


Entry Conditions: 


A 
X 
x 


= module type 
= pointer to the name string 
= DAT image pointer (for name) 


Exit Conditions: 


A 
B 
X 


U 


= module type 

= module revision number 

= updated name string; (if Register A contains 0 on 
entry) 

= module directory entry pointer 


Error Output: 
CC =C bit set on error 


B 


= appropriate error code 


Additional Information: 


8-84 


The Find Module Directory Entry call returns a pointer to 
the module directory entry for the first module that has a 
name and type matching the specified name and type. If 
you pass a module type of zero, the system call finds any 
module. 


The support module for this call is OS9p1. 
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Find 64 Returns the address 
OS9 F$Find64 103F 2F OL Ee CMOEY 
block 
Entry Conditions: 
A = block number 
X = address of the block 
Exit Conditions: 
Y = address of the block 
CC =carry set if block not allowed or not in use 


Additional Information: 


@ OS-9 uses Find 64 to find path descriptors when given 
their block number. The block number can be any positive 
integer. 
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Get Free High Searches the DAT 
image for the 

Block highest set of 

OS9 F$FreeHB 103F 3E contiguous free 


blocks of the 
specified size 
Entry Conditions: 
B = block count 
Y = DAT image pointer 
Exit Conditions: 


A =starting block number 


Error Output: 

CC =C bit set on error 

B = = appropriate error code 
Additional Information: 


® The Get Free High Block call returns the block number of 
the beginning memory address of the free blocks. 


@ The support module for this system call is OS9p1. 
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Get Free Low Searches the DAT 
image for the lowest set 

Block of contiguous free 

OS9 F$FreeLB 103F 3D blocks of the specified 
size 


Entry Conditions: 

B = block count 

Y = DAT image pointer 
Exit Conditions: 


A = starting block number 


Error Output: 

CC =C bit set on error 

B = appropriate error code 
Additional Information: 


@ The Get Free Low Block call returns the block number of 
the beginning memory address of the free blocks. 


@ The support module for this system call is OS9p1. 
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Compact Module Compacts the entries in 
Directory the module directory 
OS9 FSGCMDir 103F 52 


Entry Conditions: None 
Exit Conditions: None 


Additional Information: 


e@ This function is only for internal OS-9 system use. You 
should never call it from a program. 
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Get Process Gets a pointer to a 
Pointer prawns 
F$GProcP 103F 37 


Entry Conditions: 
A = process ID 


Exit Conditions: 


B = = pointer to process descriptor (if no error) 


Error Output: 

CC =carry set on error 

B = error code (If an error occurs (E$BPrcID)) 
Additional Information: 


@ The Get Process Pointer call translates a process ID num- 
ber to the address of its process descriptor in the system 
address space. Process descriptors exist only in the system 
task address space. Because of this, the address returned 
only refers to system address space. 


@ The support module for this call is OS9p2. 
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1/ O Delete Deletes an I/O module 
OS9 F$IODel 103F 33 that is not being used 


Entry Conditions: 
X = address of an I/O module 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ The I/O Delete deletes the specified I/O module from the 
system, if the module is not in use. This system call is 
used mainly by the I/O MANAGER, and can be of limited 
or no use for other applications. 


@ This is the order in which I/O Delete operates: 


1. Register X passes the address of a device descriptor 
module, device driver module, or file manager module. 


2. OS-9 searches the device table for the address. 


3. If OS-9 finds the address, it checks the module’s use 
count. If the count is zero, the module is not being 
used; OS-9 deletes it. If the count is not zero, the mod- 
ule is being used; OS-9 returns an error. 


e I/O Delete returns information to the Unlink system call 
after determining whether a device is busy. 
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LV/O Queue Inserts the calling 
process into another 

OS9 FSIOQu 103F 2B process’s I/O queue, 
and puts the calling 
process to sleep 


Entry Conditions: 


A = process number 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ The I/O Queue call links the calling process into the I/O 
queue of the specified process and performs an untimed 
sleep. The IO Manager and the file managers are primary 
and extensive users of I/O Queue. 


@ Routines associated with the specified process send a wake- 
up signal to the calling process. 
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Set IRQ Adds a device to or 


OS9 F$IRQ 103F 2A removes it from the 


polling table 


Entry Conditions: 


D 
X 


bs 
U 


= address of the device status register 
= 0 (to remove a device) or the address of a packet (to 
add a device) 
@ the address at X is the flip byte 
® the address at X+1 is the mask byte 
@ the address at X +2 is the priority byte 
= address of the device IRQ service routine 
= address of the service routine’s memory area 


Error Output: 


CC =carry set on error 


B 


= error code (if any) 


Additional Information: 
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Set IRQ is used mainly by device driver routines. (See 
“Interrupt Processing” in Chapter 2 for a complete discus- 
sion of the interrupt polling system.) 


Packet Definitions: 


The Flip Byte. Determines whether the bits in the device 
status register indicate active when set or active when 
cleared. If a bit in the flip byte is set, it indicates that the 
task is active whenever the corresponding bit in the status 
register is clear (and vice versa). 


The Mask Byte. Selects one or more bits within the device 
status register that are interrupt request flag(s). One or 
more set bits identify which task or device is active. 


The Priority Byte. Contains the device priority number (0 
= lowest priority, 255 = highest priority). 


Privileged System Mode Calls / 8 


Load A F rom Loads A from 0,X in 


F$LDABX 103F 49 


Entry Conditions: 
B= task number 
X = pointer to data 
Exit Conditions: 
A = byte at 0,X in task address space 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


e@ The value in Register X is an offset value from the begin- 
ning address of the Task module. The Load A From Task B 
call returns one byte from this logical address. Use this 
system call to get one byte from the current process’s mem- 
ory in a system state routine. 
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Get One Byte Loads A from [X, [YJ] 
F$LDAXY 103F 46 


Entry Conditions: 


X 
Y 


= block offset 
= DAT image pointer 


Exit Conditions: 


A 


= contents of byte at DAT image (Y) offset by X 


Error Output: 


CC =carry set on error 


B 


= error code (if any) 


Additional Information: 
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The Get One Byte system call gets the contents of one byte 
in the specified memory block. The block is specified by the 
DAT image in (Y), offset by (X). The call assumes that the 
DAT image pointer is to the actual block desired, and that 
X is only an offset within the DAT block. The value in Reg- 
ister X must be less than the size of the DAT block. OS-9 
does not check to see if X is out of range. 


a 


Privileged System Mode Calls / 8 


Get Two Bytes Loads D from 
F$LDDDXY 103F 48 [D+ X],[Y] 


Entry Conditions: 


D = Offset to the offset within the DAT image 
X = Offset within the DAT image 
Y = DAT image pointer 


Exit Conditions: 
D  ~=contents of two bytes at [D+ X,Y] 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ Get Two Bytes loads two bytes from the address space 
described by the DAT image pointer. If the DAT image 
pointer is to the entire DAT, then make D+ X equal to the 
process address for data. If the DAT image is not the entire 
image (64K), then you must adjust D+X relative to the 
beginning of the DAT image. Using D+ X lets you keep a 
local pointer within a block, and also lets you point to an 
offset within the DAT image that points to a specified block 
number. 
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Map Specific Maps the specified 

Block block(s) into 
unallocated blocks of 

F$MapBlk 103F 4F process space 


Entry Conditions: 
X = starting block number 
B = number of blocks 
Exit Conditions: 
U = address of first block 


Error Output: 
B = error code (if any) 
CC =carry set on error 
Additional Information: 


@ The system maps blocks from the top down. It maps new 
blocks into the highest available addresses in the address 
space. See Clear Specified Block for information on 
unmapping. 
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Move Data Moves data bytes from 
F$Move 103F 38 one address space to 
another 


Entry Conditions: 


= source task number 

= destination task number 
source pointer 

= byte count 

= destination pointer 


CK Kw SP 
| il 


Error Output: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 


@ You can use the Move Data system call to move data bytes 
from one address space to another, usually from system to 
user, or vice versa. 


@ The support module for this call is OS9p1. 
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Next Process Executes the next 


OS9 F$NProc 103F 2D process in the active 
process queue 


Entry Conditions: None 


Exit Conditions: 


Control does not return to caller. 


Additional Information: 


@ The Next Process system call takes the next process out of 
the active process queue and initiates its execution. If the 
queue contains no process, OS-9 waits for an interrupt, and 
then checks the queue again. 


@ The process calling Next Process must already be in one of 
the three process queues. If it is not, it becomes unknown 
to the system even though the process descriptor still exists 
and can be displayed by a PROCS command. 
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Release A Task Releases a specified 
F$RelTsk 103F 43 DAT task number from 
use by a process, 
making the task’s DAT 
hardware available for 
use by another task 


Entry Conditions: 


B = task number 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ The support module for this call OS9p1. 
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Re serve Task Reserves a DAT task 
Number number 
F$ResTsk 103F 42 


Entry Conditions: none 


Exit Conditions: 


B = task number (if no error) 


Error Output: 

CC =carry set on error 

B = error code if an error occurs 
Additional Information: 


@ The Reserve Task Number call finds a free DAT task num- 
ber, reserves it, and returns the task number to the caller. 
The caller often then assigns the task number to a process. 


@ The support module for this call is OS9p1. 
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Return 64 Deallocates a 64-byte 
OS9 F$Ret64 103F 31 block of memory 


Entry Conditions: 

A = block number 

X = address of the base page 
Error Output: 

CC =carry set on error 

B = error code (if any) 
Additional Information: 


@ See the Allocate 64 system call for more information. 
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Set Process DAT Copies all or part of 

the DAT image into a 
Image process descriptor 
F$SetImg 103F 3C 


Entry Condition: 


= starting image block number 
= block count 

process descriptor pointer 

= new image pointer 


Cx WLS 
| 


Error Output: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 


@ While copying part or all of the DAT image, this system 
call also sets an image change flag in the process descrip- 
tor. This flag guarantees that as a process returns from 
the system call. The call updates the hardware to match 
the new process DAT image. 


@ The support module for this call is OS9p1. 
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Set Process Task writes to the hardware 
DAT Registers DAT registers 


F$SetTsk 103F 41 


Entry Conditions: 


X = pointer to process descriptor 


Error Output: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 


@ This system call sets the process task hardware DAT regis- 
ters, and clears the image change flag in the process 
descriptor. It also writes to DAT RAM the process’s seg- 
ment address information. 


@ The support module for this call is OS9p1. 
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System Link Adds a module from 
‘ outside the current 
F$SLink 103F 34 address space into the 
current address space 


Entry Conditions: 


A = module type 
X = module name string pointer 
Y  =name string DAT image pointer 


Exit Conditions: 


module type 

module revision (if no error) 
updated name string pointer 
module entry point 

module pointer 


CK Kw Pp 
lou ue ue ll 


Error Output: 
CC =carry set on error 
= error code (If an error occurs) 
Additional Information: 


@ The I/O System uses the System Link call to link into the 
current process’s address space those modules specified by a 
device name in a user call. User calls such as Create File 
and Open Path use this System Link. 


@ The support module for this call is OS9p1. 
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Request System Allocates a block of 
memory of the 

Memory specified size from the 

OS9 F$SRqMem 103F 28 top of available RAM 


Entry Conditions: 
D- = byte count 


Exit Conditions: 
U = starting address of the memory area 
D =new memory size 
Error Output: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 


@ The Request System Memory call rounds the size request 
to the next page boundary. 


@ This call allocates memory only for system address space. 
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Return System Deallocates a block of 
Memory contiguous pages 
OS9 F$SRtMem 103F 29 


Entry Conditions: 


U = starting address of memory to return; must point to an 
even page boundary 
D =number of bytes to return 


Error Output: 
CC =carry set on error 
B = error code (if any) 
Additional Information: 
@ Register U must point to an even page boundary. 


@ This call deallocates memory for system address space only. 
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Set SVC Adds or replaces a 


OS9 F$SSve 103F 32 system call 


Entry Conditions: 
Y = address of the system call 
initialization table 
Error Output: 
COC =. bit set 
B = error code 
Additional Information: 


@ Set SVC adds or replaces a system call, which you have 
written, to OS-9’s user and system mode system call tables. 


@ Register Y passes the address of a table, which contains the 
function codes and offsets, to the corresponding system call 
handler routines. This table has the following format: 


Relative Use 


Address 
$00 

Function Code + First entry 
$01 __ Offset From Byte 3 __ 
$02 To Function Handler 
$03 Function Code < Second entry 
$04 Offset From Byte 6 
$05 To Function Handler _ 

More Entries + More entries 

$80 + End-of-table mark 
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If the most significant bit of the function code is set, OS-9 
updates the system table. 


If the most significant bit of the function code is not set, 
OS-9 updates the system and user tables. 


The function request codes are in the range $29-$34. IO 
calls are in the range $80-$90 


To use a privileged system call, you must be executing a 
program that resides in the system map and that executes 
in the system state. 


The system call handler routine must process the system 
call and return from the subroutine with an RTS 
instruction. 


The handler routine might alter all CPU registers (except 
Register SP). 


Register U passes the address of the register stack to the 
system call handler as shown in the following diagram: 


Relative Name 
Address 

$00 | RSCC 
$01 R$D 
$01 RSA 
$02 R$B 
$03 RSDP 
$04 R$X 
$06 RSY 
$08 R$U 
$0A R$PC 


Codes $70-$7F are reserved for user definition. 
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Store A Byte Stores A at 0,X in 
In A Task | tase) 


FSSTABX 103F 4A 


Entry Conditions: 


A = byte to store 
B = destination task number 
X = logical destination address 


Error Output: 
CC = carry set on error 
B = error code (if any) 
Additional Information: 


@ This system call is similar to the assembly language 
instruction “STA 0,X”. The difference is that in the system 
call, X refers to an address in the given task’s address 
space, instead of the current address space. 


@ The support module for this system call is OS9p1. 
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Install virtual Installs a virtual 
interrupt interrupt handler 
p routine 


OS9 F$VIRQ 103F 27 


Entry Conditions: 


D- = initial count value 
X = 0 to delete entry 
1 to install entry 
Y = address of 5-byte packet 


Error Output: 


CC =carry set on error 
B = appropriate error code 


Additional Information: 


@ Install VIRQ for use with devices in the Multi-Pak Expan- 


sion Interface. This call is explained in detail in Chapter 2. 
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Validate Module Checks the module 


OS9 F$VModul 103F 2E header parity and CRC 
bytes of a module 


Entry Conditions: 

D- = = DAT image pointer 

X = new module block offset 
Exit Conditions: 


U = address of the module directory entry 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


e If the values of the specified module are valid, OS-9 
searches the module directory for a module with the same 
name. If one exists, OS-9 keeps in memory the module that 
has the higher revision level. If both modules have the save 
revision level, OS-9 retains the module in memory. 
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Get Status System Calls 


You use the Get Status system calls with the RBF manager sub- 
routine GETSTA. The OS-9 Level Two system reserves function Wy 
Codes 7-127 for use by Microware. You can define Codes 128-255 

and their parameter-passing conventions for your own use. (See 

the sections on device drivers in Chapters 4, 5, and 6.) 


The Get Status routine passes the register stack and the speci- 
fied function code to the device driver. 


Following are the Get Status functions and their codes. 


SS.OPT 


(Function code $00). Reads the option section of the path 
descriptor, and copies it into the 32-byte area pointed to by Reg- 
ister X 


Entry Conditions: 


A = path number 
= WY 
X = address to receive status packet 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ Use SS.OPT to determine the current settings for editing 
functions, such as echo and auto line feed. 
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SS.RDY 


(Function code $01). Tests for data available on SCF-supported 
devices 


Entry Conditions: 


A = path number 
B = $01 


Exit Conditions: 


If the device is ready: 
CC =carry clear 
B = $00 


If the device is not ready: 
CC =carry set 
B = $F6 (ES$SRNDY) 


Error Output: 


CC =carry set 
B = error code 


SS.SIZ 


(Function code $02). Gets the current file size on a RBF-sup- 
ported devices only 


Entry Conditions: 


A = path number 
B = $02 
Exit Conditions: 
X = most significant 16 bits of the current file size 
U- = least significant 16 bits of the current file size 


Error Output: 


CC =carry set on error 
B- =error code (if any) 
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SS.POS 


(Function code $05). Gets the current file position (RBF-sup- 
ported devices only) 


Entry Conditions: 


A = path number 
B = $05 
Exit Conditions: 
X = most significant 16 bits of the current file position 
U = least significant 16 bits of the current file position 


Error Output: 


CC =carry set on error 
B = error code (if any) 
SS.EOF 


(Function code $06). Tests for the end of the file (EOF) 
Entry Conditions: 


A = path number 
B = $06 


Exit Conditions: 
If there is no EOF: 


CC = earry clear 
B = $00 


If there is an EOF: 
CC =carry set 
B = $D3 (E$SEOF) 


Error Output: 


CC =carry set 
B = error code 
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SS.DevNm 
(Function Code $0E). Returns a device name 
Entry Conditions: 


A = path number 
B = $0E 
X = address of 32-byte buffer for name 


Exit Conditions: 
X = address of buffer, name moved to buffer 


SS.DSTAT 
(Function code $12). Returns the display status 
Entry Conditions: 


A = path number 
B = $12 


Exit Conditions: 


A =color code of the pixel at the cursor address 
X = address of the graphics display memory 
Y = graphics cursor address; X = MSB, Y = LSB 


Additional Information: 


@ This function is supported only with the VDGINT module 
and deals with VDG-compatible graphics screens. See 
SS.AAGBf for information regarding Level Two operation. 
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SS.JOY 
(Function code $13). Returns the joystick values 


Entry Conditions: 


A = path number 
B =6$13 
X = joystick number 


0 = (right joystick) 
1 = (left joystick) 


Exit Conditions: 


A = fire button down 

0 = none 

1 = Button 1 

2 = Button 2 

3 = Button 1 and Button 2 
X = selected joystick x value (0-63) 
Y = selected joystick y value (0-63) 

Note: Under Level 1, the following values are returned by 
this call: 

A = fire button status 

$FF = fire button is on 

$00 = fire button is off 
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SS.AlfaS 


(Function code $1C). Returns VDG alpha screen memory 
information 


Entry Conditions: 


A = path number 
B =$1C 


Exit Conditions: 


A =caps lock status 

$00 = lower case 

SFF = upper case 
X = memory address of the buffer 
Y = = memory address of the cursor 


Additional Information: 


@ SS.AlfaS maps the screen into the user address space. The 
call requires a full block of memory for screen mapping. 
This call is only for use with VDG text screens handled by 
VDGINT. 


@ The support module for this call is VDGINT. 


@ Warning: Use extreme care when poking the screen, since 
other system variables reside in screen memory. Do not 
change any addresses outside of the screen. 
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SS.Cursr 


(Function code $25). Returns VDG alpha screen cursor 
information 


Entry Conditions: 


A = path number 
B =$25 
Exit Conditions: 
A =character code of the character at the current cursor 
address 
X  =cursor X position (column) 
Y  =cursor Y position (row) 


Additional Information: 


e SS.Cursr returns the character at the current cursor posi- 
tion. It also returns the X-Y address of the cursor relative 
to the current device’s window or screen. SS.Cursr works 
only with text screens. 


@ The support module for this call is VDGINT. 
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SS.ScSiz 
(Function code $26). Returns the window or screen size 
Entry Conditions: 


A = path number 
B = $26 


Exit Conditions: 


X = number of columns on screen/window 
Y = number of rows on screen/window 


Additional Information: 


@ Use this call to determine the size of an output screen. The 
values returned depend on the device in use: 


For non-CCIO devices, the call returns the values follow- 
ing the XON/XOFF bytes in the device descriptor. 


For CCIO devices, the call returns the size of the window 
or screen in use by the specified device. 


For window devices. the call returns the size of the cur- 
rent working area of the window. 


@ The support modules for this call are VDGINT, GrflInt, and 
WindInt. 
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SS.KySns 


(Function code $27). Returns key down status 


Entry Conditions: 


A 
B 


Exit 
A 


= path number 
= $27 


Conditions: 


= keyboard scan information 


Additional Information: 
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Accumulator A returns with a bit pattern representing 
eight keys. With each keyboard scan, OS9 updates this bit 
pattern. A set bit (1) indicates that a key was pressed since 
the last scan. A clear bit (0) indicates that a key was not 
pressed. Definitions for the bits are as follows: 


Bit Key 

0 

or 
or 

(up arrow) 
(down arrow) 
(left arrow) 
(right arrow) 
Space Bar 


“ID OP GDF 


The bits can be masked with the following equates: 


SHIFTBIT equ %00000001 
CNTRLBIT equ %00000010 
ALTERBIT equ %00000100 
UPBIT equ %00001000 
DOWNBIT equ %00010000 
LEFTBIT equ %00100000 
RIGHTBIT equ %01000000 
SPACEBIT equ %10000000 


The support module for this call is CC3IO. 
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SS.ComSt 


(Function code $28). Return serial port configuration 
information 


Entry Conditions: 


A = path number 
B = $28 
Exit Conditions: 
Y  =high byte: parity 


low byte: baud rate 
(See the Setstat call SS.ComSt for values) 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ The SCF manager uses this call when performing an 
SS.Opt Getstat on an SCF-type device. User calls to 
SS.ComSt do not update the path descriptor. Use the 
SS.OPT Getstat call for most applications, because it auto- 
matically updates the path descriptor. 
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SS.MnSel 


(Function code $87). Requests that the high-level menu handler 
take control of menu selection 


Entry Conditions: 


A = path number 
B = $87 
Exit Conditions: 
A = menu ID (if valid selection) 
O (if invalid selection) 
B = item number of menu (if valid selection) 


Error Output: 


CC =carry set on error 
B = error code (if invalid selection) 


Additional Information: 


e After detecting a valid mouse click (when the mouse is 
pointing to a control area on a window), a process needs to 
call SS.MnSel. This call tells the enhanced window inter- 
face to handle any menu selection being made. If accumula- 
tor A returns with 0, then no selection has been made. The 
calling process needs to test and handle other returned 
values. 


e A condition where Register A returns a valid menu ID 
number and Register B returns 0 signals the selection of a 
menu with no items. The application can now take over and 
do a special graphics pull down of its own. The menu title 
remains highlighted until the application calls the 
SS.UMBar SetStat to update the menu bar. 


e@ The support module for this call is WindInt. 
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SS.Mouse 
(Function code $89). Gets mouse status 
Entry Conditions: 


A = path number 
B = $89 
X = data storage area address 
Y = = mouse port select: 
0 = automatic selection 


1 = right side 
2 = left side 
Exit Conditions: 
X = data storage area address 
Error Output: 
CC =carry set on error 
B = error code (if any) 
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Additional Information: 


e SS.Mouse returns information on the current mouse and its 
fire button. The following list defines the 32-byte data 
packet that SS.Mouse creates: 


8-124 


Pt. Valid rmb 1 Is returned info valid? (O=no, 
1 = yes) 
Pt.Actv rmb 1 Active side (0 = off, 1 = right, 2 = 
left) 
Pt. ToTm rmb 1 Timeout initial value 
PeTris rmb 1 Time until timeout 
rmb 2 RESERVED 
Pt.TSSt rmb 2 Time since counter start 
Pt.CBSA rmb 1 Current button state (Button A) 
Pt.CBSB rmb 1 Current button state (Button B) 
Pt.CcCtA rmb 1 Click count (Button A) 
Pt.CCtB rmb 1 Click count (Button B) 
Pt.TTSA rmb 1 Time this state counter (Button A) 
Pt.TTSB rmb 1 Time this state counter (Button B) 
Pt.TLSA rmb 1 Time last state counter (Button A) 
Pt.TLSB rmb 1 Time last state counter (Button B) 
rmb 2 RESERVED 
Pt.BDX rmb 2 Button down frozen Actual X 
Pt. BDY rmb 2 Button down frozen Actual Y 
Pt.Stat rmb 1 Window pointer type location 
Pt.Res rmb 1 Resolution (0-640 by 0=10/1=1) 
Pt.AcX rmb 2 Actual X value 
Pt.AcY rmb 2 Actual Y value 
Pt.WRX rmb 2 Window relative X 
Pt. WRY rmb 2 Window relative Y 
Pt.Siz equ . Packet size 32 bytes 
SPt.SRX rmb 2 System use, screen relative X 
SPt.SRY rmb 2 System use, screen relative Y 
SPt.Siz equ . Size of packet for system use 


Button Information: 


Pt.Valid. The valid byte gives the caller an indication of 
whether the information contained in the returned packet 
is accurate. The information returned by this call is only 
valid if the process is running on the current interactive 
window. If the process is on a non-interactive window, the 
byte is zero and the process can ignore the information 
returned. | 
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Pt.Actv. This byte shows which port is selected for use by 
all mouse functions. The default value is Right (1). You can 
change this value with the SS.GIP Setstat call. 


Pt.ToTm. This is the initial value used by Pt.TTTo. 


Pt.TTTo. This is the count down value (as of the instant 
the Getstat call is made). This value starts at the value 
contained in the Pt.ToTm and counts down to zero at a rate 
of 60 counts per second. The system maintains all counters 
until this value reaches 0, at which point it sets all 
counters and states to 0. The mouse scan routine changes 
into a quiet mode which requires less overhead than when 
the mouse is active. The timeout begins when both buttons 
are in the up (open) state. The timer is reinitialized to the 
value in Pt.ToTm when either button goes down (closed). 


Pt.TSSt. This counter is constantly increasing, beginning 
when either button is pressed while the mouse is in the 
quiet state. All counts are a number of ticks (60 per sec- 
ond). The timer counts to $FFFF, then stays at that value 
if additional ticks occur. 


Pt.CBSA. These flag bytes indicate the state of the button 
Pt.CBSB. at the last system clock tick. A value of 0 indi- 
cates that the button is up (open).. A value other than zero 
indicates that the button is down (closed). Button A is 
available on all Tandy joysticks and mice. Button B is only 
available for products that have two buttons. 


The system scans the mouse buttons each time it scans the 
keyboard. 


Pt.CCtA. This is the number of clicks that have occurred 
Pt.CCtB. since the mouse went into an active state. A 
click is defined as pressing (closing) the button, then releas- 
ing (opening) the button. The system counts the clicks as 
the button is released. 


Pt.TTSA. This counter is the number of ticks that have 
Pt.TTSB. occurred during the current state, as defined by 
Pt.CBSx. This counter starts at one (counts the tick when 
the state changes) and increases by one for each tick that 
occurs while the button remains in the same state (open or 
closed). 
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Pt.TLSA. This counter is the number of ticks that have 
Pt.TLSB. occurred during the time that a button is in a 
state opposite of the current state. Using this count and 
the TTSA/TTSB count, you can determine how a button 
was in the previous state, even if the system returns the 
packet after the state has changed. Use these counters, 
along with the state and click count values, to define any 
type of click, drag, or hold convention you want. 


Reserved. Two packet bytes are reserved for future expan- 
sion of the returned data. 


Position Information: 


Pt.BDX. These values are copies of the Pt.AcX and Pt.AcY 
Pt.BDY. values when either of the buttons change from an 
open state to a closed state. 


Pt.Stat. This byte contains information about the area of 
the screen on which the mouse is positioned. Pt. Valid must 
be a value other than 0 for this information to be accurate. 
If Pt. Valid is 0, this value is also 0 and not accurate. Three 
types of areas are currently defined: 


0 = content region or current working area of the 
window 

1 = control region (for use by Multi- View) 

2 = off window, or on an area of the screen that is not 


part of the window 


Pt.Res. This value is the current resolution for the mouse. 
The mouse must always return coordinates in the range of 
0-639 for the X axis and 0-191 for the Y axis. If the system 
is so configured, you can use the high-resolution mouse 
adapter which provides a 1 to 1 ratio with these values plus 
1. If the adapter is not in use, the resolution is a ratio of 1 
to 10 on the X axis and 1 to 3 on the Y axis. The keyboard 
mouse provides a resolution of 1 to 1. The values in Pt.Res 
are: 

0 

1 


Pt.AcX. The values read from the mouse returned in the 
Pt.AcyY. resolution as described under Pt.Res. 


low res (x:10, y:3) 
high res (x,y:1) 
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Pt.WRX. The values read from the mouse minus the 
Pt.WRY. starting coordinates of the current window’s 

es working area. These values return the coordinates in num- 

| bers relative to the type of screen. For example, the X axis 
is in the range 0-639 for high-resolution screens and 0-319 
for low resolution screens. You can divide the window rela- 
tive values by 8 to obtain absolute character positions. 
These values are most helpful when working in non-scaled 
modes. 


@ The support modules for this call are CC3I0O, GrfInt, and 
WindInt. 


SS.Palet 
(Function code $91). Gets palette information 


Entry Conditions: 


A = path number 
B =6$91 
oo X = pointer to the 16-byte palette information buffer 


Exit Conditions: 


X = pointer to the 16-byte palette information buffer 
Additional Information: 


@ SS.Palet reads the contents of the 16 screen palette regis- 
ters, and stores them in a 16-byte buffer. When you make 
the call, be sure the X register points to the desired buffer 
location. The pointer is retained on exit. The palette values 
returned are specific to the screen on which the call is 
made. 


@ The support modules for this call are VDGINT, Grfint, and 
WindInt. 
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SS.ScTyp 


(Function code $93). Returns the type of a screen to a calling 
program. 


Entry Conditions: 


A = path 
B = $93 


Exit Conditions: 


A =screen type code 

oe = 40 x 24 text screen 
80 x 24 text screen 
not used 
not used 
640 x 192, 2-color graphics screen 
320 x 192, 4-color graphics screen 
640 x 192, 4-color graphics screen 
320 x 192, 16-color graphics screen 


COmNI OS) OP OC DO 
low ue i ul ell 


Additional Information: 


@ Support modules for this system call are GrfInt and 
WindInt. 
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SS.FBRgs 


(Function code $96). Returns the foreground, background and 
border palette registers for a window. 


Entry Conditions: 


A = path number 

B = $96 
Exit Conditions: 

A = foreground palette register number 

B= background palette register number (if carry clear) 

X = least significant byte of border palette register number 
Error Output: 

B = error code if any 

CC =carry set on error 


Additional Information: 
@ Support modules for SS.FBRgs are GrfInt and WindInt. 


SS.DFPal 


(Function code $97). Returns the default palette register 
settings. 


Entry Conditions: 


A = path number 
B = $97 
X = pointer to 16-byte data space 


Exit Conditions: 
X = default palette data moved to user space 
Error Output: 


B  =error code, if any 
CC =carry set on error 
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Additional Information: 


e You can use SS.DFPal to find the values of the default pal- 
ette registers that are used when a new screen is allocated 
by GrfInt or WindInt. The corresponding SetStat can alter 
the default registers. This GetStat/SetStat pair is for sys- 
tem configuration utilities and should not be used by gen- 
eral applications. 


Set Status System Calls 


Use the Set Status system calls with the RBF manager subrou- 
tine SETSTA. The OS-9 Level Two system reserves function 
Codes 7-127 for use by Microware. You can define Codes 200-255 
and their parameter-passing conventions for your own use. (See 
the sections on device drivers in Chapters 4, 5, and 6.) 


Following are the Set Status functions and their codes. 


SS.OPT 


(Function code $00). Writes the option section of the path 
descriptor 


Entry Conditions: 


A = path number 

B = 4600 

X = address of the status packet 
Error Output: 

CC =carry set on error 

B = error code (if any) 


Additional Information: 


@e SS.OPT writes the option section of the path descriptor 
from the 32-byte status packet pointed to by Register X. 
Use this system call to set the device operating parameters, 
such as echo and line feed. 
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SS.SIZ 


(Function code $02). Changes the size of a file for RBF-type 
devices 


Entry Conditions: 


A = path number 

B =$02 

X = most significant 16 bits of the desired file size 
U- = least significant 16 bits of the desired file size 


Error Output: 


CC =carry set on error 
B = error code (if any) 
SS.RESET 


(Function code $03). Restores the disk drive head to Track 0 in 
preparation for formatting and error recovery (use only with 
RBF-type devices) 


Entry Conditions: 


A = path number 
B = $03 
Error Output: 
CC =carry set on error 
B = error code (if any) 
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SS.WTRK 


(Function code $04). Formats (writes) a track on a disk (RBF- 
type devices only) 


Entry Conditions: 


A = path number 
B = $04 
U = track number (least significant 8 bits) 


X = address of the track buffer 
Y = = side/density 


Bit BO = side 
0 = Side 0 
1 = Side 1 
Bit Bl = density 
0 = single 
1 = double 
Error Output: 
CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ For hard disks or floppy disks that have a “format entire 
diskette command,” SS.WTRK formats the entire disk only 
when the track number is zero. 
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SS.SQD 


(Function code $0C). Starts the shutdown procedure for a hard 
disk that has sequence-down requirements prior to removal of 
power. (Use only with RBF-type devices.) 


Entry Conditions: 


A = path number 
B = $0C 


Exit Conditions: None 


SS.KySns 
(Function code $27). Turns the key sense function on and off 


Entry Conditions: 


A = path number 
B = $27 
X = key sense switch value 


normal key operation 


1 = key sense operation 
Error Output: 
CC =carry set on error 
B= error code (if any) 


Additional Information: 


@ When SS.KySns switches the keyboard to key sense mode, 
the CC3IO module suspends transmission of keyboard char- 
acters to the SCF manager and the user. While the com- 
puter is in key sense mode, the only way to detect key press 
is with SS.KySns. 


@ The support module for this call is CC3IO. 
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SS.ComSt 


(Function code $28). Used by the SCF manager to configure a 
serial port 


Entry Conditions: 


A = path number 
B = $28 
Y  =high byte: parity 


low byte: baud rate 
Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


Baud Configuration. The high order byte of Y determines the 
baud rate, the word length, and number of stop bits. The byte is 
configured as follows: 


poBpau |!7le6elsl4a4i3l2iilo! 


oom sual Baud rate 
Reserved 
Word length 


Stop bits 
Stop bits: 
Oo 1 
Ie 2 
Word length: 
00 = 8 bit 
O17 Dit 
Baud rate: 
0000 = 110 
0001 = 300 
0010 = 600 
UOLL = 1200 
0100 = 2400 
0101 = 4800 
0110 = 9600 
O111 — 19200 
1xxx = undefined 
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e Parity Configuration. The low order byte of Y determines 
parity. The byte is configured as follows: 


PD.BAU |71l6lsl4i3il2lilo| 


Special use 


Parity 
Parity: 
xx0 = none 
001 = odd (ACIAPAK and MODPAK only) 
011 = even (ACIAPAK and MODPAK only) 
101 = transmit: mark 
receive: ignore 
111 = transmit: space 


receive: ignore 


@ The SCF manager uses SS.ComSt to inform a driver that 
serial port configuration information has been changed in 
the path descriptor. After calling SS.ComSt, a user routine 
must call the SS.OPT SetStat to correctly update the path 
descriptor. 


e@ This call is for the use of the SCF manager. Use SS.OPT 
for changing baud, stop bit, and parity values. 


SS.Close 


(Function code $2A). Informs a device driver that a path is 
closed. 


Additional Information: 


This call is used internally by OS-9’s SCF file manager and is 
not available for user programs. It can be used only by device 
drivers and file managers. 
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SS.AAGBf 
(Function code $80). Reserves an additional graphics buffer 
Entry Conditions: 


A = path number 
B = $80 


Exit Conditions: 


X = buffer address 
Y = buffer number (1-2) 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


e SS.AAGBf allocates an additional 8K graphics buffer. The 
first buffer (Buffer 0) must be allocated by using the DIS- 
PLAY GRAPHICS command. To use the DISPLAY GRAPH- 
ICS command, send control code $0F to the standard 
terminal driver. SS.AAGBf can allocate up to two addi- 
tional buffers (Buffers 1 and 2), one at a time. 


e After calling SS.AAGBf, Register X contains the address of 
the new buffer. Register Y contains the buffer number. 


@ To deallocate all graphics buffers, use the END GRAPHICS 
control code. 


@ When SS.AAGBf allocates a buffer, it also maps the buffer 
into the application’s address space. Each buffer uses 8K of 
the available memory in the application’s address space. 
Also, if SS.DStat is called, Buffer 0 is also mapped into the 
application’s address space. Allocation of all three buffers 
reduces the application’s free memory by 24K. 


@ The support module for this call is VDGINT. 


8-136 


System Calls / 8 


SS.SLGBf 
(Function code $81). Selects a graphics buffer 


Entry Conditions: 


A 
B 
X 


xX 


= path number 
= $81 
= $00 select buffer for use 
$01-$FF select buffer for use and display 
= buffer number (0-2) 


Exit Conditions: 


X 
¥ 


unchanged from entry 
unchanged from entry 


Error Output: 


CC =carry set on error 


B 


= error code (if any) 


Additional Information: 


Use DISPLAY GRAPHICS to allocate the first graphics 
buffer. Use SS.AAGBf to allocate the second and third 
graphics buffers. 


Save each return address when writing directly to a screen. 
It is not necessary to save return addresses when using 
operating system graphics commands. 


SS.SLGBf does not update hardware information until the 
next vertical retrace (60Hz rate). Programs that use 
SS.AAGBf to change current draw buffers need to wait long 
enough to ensure that OS-9 has moved the current buffer to 
the screen. 


The screen shows the buffer only if the buffer is selected as 
the interactive device. If the device does not possess the 
keyboard, OS-9 stores the information until the device is 
selected as the interactive device. When the device is 
selected as the interactive device, the display shows the 
selected device’s screen. 


The support module for this call is VDGINT. 
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SS.MpGPB 


(Function code $84). Maps the Get/Put buffer into a user 
address space 


Entry Conditions: 


A = path number 
B = $84 
X =high byte: buffer group number 
low byte: buffer number 
Y = action to take 
1 = map buffer 
0 = unmap buffer 


Exit Conditions: 


X = address of the mapped buffer 


Y = number of bytes in buffer 
Error Output: 

CC =carry set on error 

B = error code (if any) 


Additional Information: 
@ The support modules for this call are GrfInt and WindInt. 


@ SS.MpGPB maps a Get/Put buffer into the user address 
space. You can then save the buffer to disk or directly mod- 
ify the pixel data contained in the buffer. Use extreme care 
when modifying the buffer so that you do not write outside 
of the buffer data area. 
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SS.WnSet 
(Function code $86). Set up a high level window handler 
Entry Conditions: 


A = path number 
B = $86 
xX window data pointer (if Y= WT.FSWin or WT.Win) 


4 
Error Output: 


window type code 


CC =carry set on error 
B  =error code (if any) 


Additional Information: 


@ The C language data structures for windowing are defined 
in the wind.h file in the DEFS directory of the system disk. 


e@ The support module for this call is WindInt. 


SS.SBar 
(Function code $88). Puts a scroll block at a specified position 


Entry Conditions: 


A = path number 

B = $88 

X = horizontal position of scroll block 

Y = vertical position of scroll block 
Error Output: 

CC =carry set on error 

B = error code (if any) 


Additional Information: 


@ WT.FSWin-type windows have areas at the bottom and 
right sides to indicate their relative positions within a 
larger area. These areas are called scroll bars. SS.SBar 
gives an application the ability to maintain relative posi- 
tion markers within the scroll bars. The markers indicate 
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the location of the current screen within a larger screen. 
Calling SS.SBar, updates both scroll markers. 


@ The support module for this call is WindInt. 


SS.Mouse 


(Function code $89). Sets the sample rate and button timeout 
for a mouse 


Entry Conditions: 


A = path number 
B = $89 
X = mouse sample rate and timeout 


most significant byte = mouse sample rate 
least significant byte = mouse timeout 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ SS. Mouse allows the application to define the mouse 
parameters. The sample rate is the number of clock ticks 
between the actual readings of the mouse status. 


@ The support module for the call is CC3I0O. 
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SS.MsSig 


(Function code $8A). Sends a signal to a process when the 
mouse button is pressed 


Entry Conditions: 
A = path number 


B = $8A 

X = user defined signal code (low byte only) 
Error Output: 

CC =carry set on error 

B = error code (if any) 


Additional Information: 


® SS.MsSig sends the process a signal the next time a mouse 
button changes state (from open to closed). Once SS.MsSig 
sends the signal, the process must repeat the Setstat each 
time that it needs to set up the signal. 


@ Processes using SS.MsSig should have an intercept routine 
to trap the signal. By intercepting the signal, other pro- 
cesses can be notified when the change occurs. Therefore, 
the other processes do not need to continually poll the 
mouse. 


e The SS.Relea Setstat clears the pending signal request, if 
desired. It also clears any pending signal from SS.SSig. 
Because of this, if you want to clear only one signal, you 
must reset the other signal after calling SS.MsSig. 


@ The support module for this call is CC3I0. 
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SS.AScrn 


(Function code $8B). Allocates and maps a high-resolution 
screen into an application address space 


Entry Conditions: 


A = path number 
B = $8B 
X = screen type 
= 640 x 192 x 2 colors (16K) 
1 = 320 x 192 x 4 colors (16K) 
2 = 160 x 192 x 16 colors (16K) 
3 = 640 x 192 x 4 colors (32K) 
4 = 320 x 192 x 16 colors (32K) 
Exit Conditions: 
X = application address space of screen 
Y = screen number (1-3) 
Error Output: 
CC =carry set on error 
B = error code (if any) 


Additional Information: 


SS.AScrn is particularly useful in systems with minimal 
memory when you want to allocate a high resolution graph- 
ics screen with all screen updating handled by a process. 


This call uses VDGInt (GRFINT is not required). 


All screens are allocated in multiples of 8K blocks. You can 
allocate a maximum of three buffers at one time. To select 
between buffers, use the SS.DScrn Setstat call. 


Screen memory is allocated but not cleared. The application 
using the screen must do this. 


Screens must be allocated from a VDG-type device—a 
standard 32-column text screen must be available for the 
device. 


The support module for this call is VDGINT. 
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SS.DScrn 


(Function code $8C). Causes VDGINT to display a screen that 
was allocated by SS.AScrn 


Entry Conditions: 


A = path number 
B = $8C 
x = screen number (1-3) 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ SS.DScrn shows the requested screen if the requested 
screen is the current interactive device. 


@ The support module for this call is VDGINT. 
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SS.FScrn 


(Function code $8D). Frees the memory of a screen allocated 
by SS.AScrn 


Entry Conditions: 


A = path number 
B = $8D 
¥ = screen number (1-3) 


Error Output: 


CC =carry set on error 
B = error code (if any) 


Additional Information: 


@ Do not attempt to free a screen that is currently on the 
display. 


e SS.FScrn returns the screen memory to the system and 
removes it from an application’s address space. 


@ The support module for this call is VDGINT. 
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SS.PScrn 
(Function code $8E). Converts a screen to a different type 


Entry Conditions: 


A = path number 

B = $8E 

X = new screen type 
0 = 640 x 192 x 2 colors (16K) 
1 = 820 x 192 x 4 colors (16K) 
2 = 160 x 192 x 16 colors (16K) 
3 = 640 x 192 x 4 colors (32K) 
4 = 320 x 192 x 16 colors (32K) 

Es = screen number 


Error Output: 


CC = carry set on error 
B = error code (if any) 


Additional Information: 


@ SS.PScrn changes a screen allocated by SS.AScrn to a new 
screen type. You can change a 32K screen to either a 32K 
screen, or a 16K screen. You can change a 16K screen only 
to another 16K screen type. SS.PScrn updates the current 
display screen at the next clock interrupt. 


@ However, if you change a 32K screen to a 16K screen, OS-9 
does not reclaim the extra 16K of memory. This means 
that you can later change the 16K screen back to a 32K 
screen. 


@ The support module for this call is VDGINT. 
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SS.Montr 
(Function code $92). Sets the monitor type 
Entry Conditions: 


A = path number 
B = $92 
X = monitor type 


0 = color composite 
1 = analog RGB 
2 = monochrome composite 
Error Output: 
CC =carry set on error 
B = error code (if any) 


Additional Information: 


e SS.Montr loads the hardware palette registers with the 
codes for the default color set for three types of monitors. 
The system default initializes the palette for a composite 
color monitor. 


@ The monochrome mode removes color information from the 
signals sent to a monitor. 


@ When a composite monitor is in use, a conversion table 
maps colors from RGB color numbers. In RGB and mono- 
chrome modes, the system uses the RGB color numbers 
directly. 


@ The support modules for this call are VDGINT and GrfDrv. 
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SS.GIP 


(Function code $94). Sets the system wide mouse and key 
repeat parameters 


Entry Conditions: 


A = path number 
B = $94 
X = mouse resolution; in the most significant byte 


0 = low resolution mouse 
1 = optional high resolution adapter 
= mouse port location; in the least significant byte 
1 = right port 
2 = left port 
Y = = key repeat start constant; in the most significant byte 
= key repeat delay; in the least significant byte 
OOXX = no repeat 
FFFF = unchanged 


Error Output: 


CC 
B 


Additional Information: 


carry set if error 
error code, if any 


@ Because this function affects system-wide settings, it is 
best to use it from system configuration utilities and not 
from general application program. 


@ The support module for this call is CC3IO. 
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SS.UMBAR 


(Function code $95). Requests the high level menu manager to 
update the menu bar. 


Entry Conditions: 


A = path number 
B = $95 
Exit Conditions: 
CC =carry set on error 
B = error code (if any) 


Additional Information: 


e An application can call SS.UMBar when it needs to redraw 
menu bar information, such as when it enables or disables 
menus, or when it completes a window pull down and needs 
to restore the menu. 


@ The support module for this call is WindInt. 
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SS.DFPal 
(Function code $97). Sets the default palette register values 
Entry Conditions: 


A = path number 
B = $97 
X = pointer to 16 bytes of palette data 


Exit Conditions: 


X = unchanged, bytes moved to system defaults 
CC =carry set on error 
B = error code (if any) 


Additional Information: 


@® Use SS.DFPal to alter the system-wide palette register 
defaults. The system uses these defaults when it allocates a 
new screen using the DWSet command. 


@ Because this function affects system wide settings, it is 
best to use it from system configuration utilities, not gen- 
eral application programs. 
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SS.Tone 


(Function code $98). Creates a sound through the terminal 
output device. 


Entry Conditions: 


A = path number 
B =6$98 
X = duration and amplitude of the tone 


LSB = duration in ticks (60-sec) in the range 0-255 
MSB = amplitude of tone in the range 0-63 
Y = relative frequency counter (0=low, 4095 = high) 


Exit Conditions: 


These are the same as the entry conditions. There are no 
error conditions. 


Additional Information: 


@ This call produces a programmed IO tone through the 
speaker of the monitor used by the terminal device. You can 
make the call on any valid path open to term or to a win- 
dow device. 


@ The system does not mask interrupts during the time the 
tone is being produced. 


@ The frequency of the tone is a relative number ranging 
from 0 for a low frequency to 4095 for a high frequency. 
The widest variation of tones occurs at the high range of 
the scale. 
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Executable Memory Module Format 


Relative Check 
Address Use Range 
$00 
Sync Bytes ($87,$CD) 
$01 
$02 
Module Size (bytes) 
$03 
$04 
Module Name Offset header 
$05 parity 
$07 Attributes Revision 
module 
$08 Header Parity Check CRC 
$09 
Execution Offset 
$0A 
$0B 
Permanent Storage Size 
$0C 
$0D (Additional optional header 


extensions located here) 


Module Body 
object code, constants, 
and so on 


CRC Check Value 
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Device Descriptor Format 


Relative Check 
Address Use Range 
$00 

Sync Bytes ($87,$CD) 
$01 
$02 

Module Size (bytes) 

$03 
$04 

Offset to Module Name header 
$05 parity 
ee 
01 

Module 

$08 Header Parity Check CRC 
$09 

Offset to File Manager 
$0A Name String 
$0B 

Offset to Device Driver 

Name String 
sn 
$0E 
Device Controller 
SOF Absolute Physical Addr. 
(24 bit) 
$10 
$11 Initialization Table Size 
$12,.$12+n (Initialization Table) 
(Name Strings, and so on) 
CRC Check Value 
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INIT Module Format 


Relative Check 
Address Use Range 
00 
: Sync Bytes ($87,$CD) 
$01 
$02 
Module Size (bytes) 
$03 
$04 
Module Name Offset Resdar 
$05 parity 
$06 $F (Type) $1 (Lang) 
$07 Attributes Revision 
Module 
$08 Header Parity Check CRC 
$09 sit 
Forced Limit of Top 
$0A of Free RAM 
$0B 
$0C #IRQ Polling Table Entries 
$0D # Device Table Entries 
$0E 
Offset to Startup 
$0F Module Name String 
$10 
Offset to Default Mass 
$11 Storage Device Name String 
$12 
Offset to Bootstrap 
$13 Module Name String 
$14-n Name Strings 


CRC Check Value 
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Standard Floppy Disk Format 


Color Computer 3 


Physical Track Format Pattern 


Bytes 
Format (Dec) 


Header pattern 32 
(once per track) 12 


32 


Sector pattern 
(repeated 18 times) 


_— 
Co bo 


we) 
| We) On mm HO 
'Z, H DO OF CO DO DD FR ee 


Trailer pattern 
(once per track) 


Value 
(Hex) 


4K 
00 
F5 
FC 
4K 


00 

F5 

track number (0-34) 
side number (0-1) 
sector number (1-18) 
sector length code (1) 
CRC 

4E 

00 

F5 

FB 

data area 

CRC 

4E 


4E (fill to index mark) 
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System Error Codes 


The error codes are shown in both hexadecimal and decimal. The 
error codes listed include OS-9 system error codes, BASIC error 
codes, and standard windowing system error codes. 


Code Code Meaning 
HEX DEC 


$01 001 UNCONDITIONAL ABORT — An error occurred 
from which OS-9 cannot recover. All processes 
are terminated. 


$02 002 KEYBOARD ABORT — You pressed to 
terminate the current operation. 


$03 003 KEYBOARD INTERRUPT — You pressed 
[SHIFT |(BREAK] either to cause the current operation 
to function as a background task with no video 
display or to cause the current task to terminate. 


$B7 =: 1188 ILLEGAL WINDOW TYPE — You tried to 
define a text type window for graphics or used 
illegal parameters. 


$B8 184 WINDOW ALREADY DEFINED — You tried to 
create a window that is already established. 


$B9 185 FONT NOT FOUND — You tried to use a win- 
dow font that does not exist. 


$BA 186 STACK OVERFLOW — Your process (or pro- 
cesses) requires more stack space than is avail- 
able on the system. 


$BB = 187 ILLEGAL ARGUMENT — You have used an 
argument with a command that is inappropriate. 


$BD 189 ILLEGAL COORDINATES — You have given 
coordinates to a graphics command which are 
outside the screen boundaries. 


$BE 190 INTERNAL INTEGRITY CHECK — System 
modules or data are changed and no longer 
reliable. 


$BF 191 BUFFER SIZE IS TOO SMALL — The data you 
assigned to a buffer is larger than the buffer. 
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Code 
HEX DEC 
$CO 192 
$Cl1 193 
$C2 194 
SC3 195 
$C4 196 
$C8 200 
$C9 201 
$CA 202 
$CB 203 
$CC 204 
SCD. 206 
$CE 206 
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Code Meaning 


ILLEGAL COMMAND — You have issued a 
command in a form unacceptable to OS-9. 


SCREEN OR WINDOW TABLE IS FULL — You 
do not have enough room in the system window 
table to keep track of any more windows or 
screens. 


BAD/UNDEFINED BUFFER NUMBER — You 
have specified an illegal or undefined buffer 
number. 


ILLEGAL WINDOW DEFINITION — You have 
tried to give a window illegal parameters. 


WINDOW UNDEFINED — You have tried to 
access a window that you have not yet defined. 


PATH TABLE FULL — OS-9 cannot open the 
file, because the system path table is full. 


ILLEGAL PATH NUMBER — The path number 
is too large, or you specified a non-existent path. 


INTERRUPT POLLING TABLE FULL — Your 
system cannot handle an interrupt request, 
because the polling table does not have room for 
more entries. 


ILLEGAL MODE — The specified device cannot 
perform the indicated input or output function. 


DEVICE TABLE FULL — The device table does 
not have enough room for another device. 


ILLEGAL MODULE HEADER — OS-9 cannot 
load the specified module because its sync code, 
header parity, or Cyclic Redundancy Code is 
incorrect. 


MODULE DIRECTORY FULL — The module 
directory does not have enough room for another 
module entry. 


Code 
HEX DEC 
SCF 207 
$DO0 208 
$D1 209 
$D2 210 
$D3 211 
$D4 212 
$D5 213 
$D6 214 
$D7 = 215 
$D8 216 
$D9 217 
$DA 218 
$DB 219 
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Code Meaning 


MEMORY FULL — Process address space is full 
or your computer does not have sufficient memory 
to perform the specified task. 


ILLEGAL SERVICE REQUEST — The current 
program has issued a system call containing an 
illegal code number. 


MODULE BUSY — Another process is already 
using a non-shareable module. 


BOUNDARY ERROR — OS-9 has received a 
memory allocation or deallocation request that is 
not on a page boundary. 


END OF FILE — A read operation has encoun- 
tered an end-of-file character and has 
terminated. 


RETURNING NON-ALLOCATED MEMORY — 
The current operation has attempted to deallo- 
cate memory not previously assigned. 


NON-EXISTING SEGMENT — The file struc- 
ture of the specified device is damaged. 


NO PERMISSION — The attributes of the speci- 
fied file or device do not permit the requested 
Access. 


BAD PATH NAME — The specified pathlist con- 
tains a syntax error, for instance an illegal 
character. 


PATH NAME NOT FOUND — The system can- 
not find the specified pathlist. 


SEGMENT LIST FULL — The specified file is 
too fragmented for further expansion. 


FILE ALREADY EXISTS — The specified file- 
name already exists in the specified directory. 


ILLEGAL BLOCK ADDRESS — The file struc- 
ture of the specified device is damaged. 
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Code 
HEX DEC 
$DC 220 
$DD 221 
$DF 223 
$EO 224 
$E2 226 
$E3 227] 
$E4 228 
$E5 229 
$E6 230 
$E7 8231 
$E8 232 
$E9 2338 
$EA 234 
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Code Meaning 


PHONE HANGUP-DATA CARRIER DETECT 
LOST — The data carrier detect is lost on the 
RS-232 port. 


MODULE NOT FOUND — The system received 
a request to link a module that is not in the 
specified directory. 


SUICIDE ATTEMPT — The current operation 
has attempted to return to the memory location 
of the stack. 


ILLEGAL PROCESS NUMBER — The specified 
process does not exist. 


NO CHILDREN — The system has issued a wait 
service request but the current process has no 
dependent process to execute. 


ILLEGAL SWI CODE — The system received a 
software interrupt code that is less than 1 or 
greater than 3. 


PROCESS ABORTED — The system received a 
signal Code 2 to terminate the current process. 


PROCESS TABLE FULL — A fork request can- 
not execute because the process table has no 
room for more entries. 


ILLEGAL PARAMETER AREA — A fork call 
has passed incorrect high and low bounds. 


KNOWN MODULE — The specified module is 
for internal use only. 


INCORRECT MODULE CRC — The CRC for the 
module being accessed is bad. 


SIGNAL ERROR — The receiving process has a 
previous, unprocessed signal pending. 


NON-EXISTENT MODULE — The system can- 
not locate the specified module. 


Cc, 


Code 
HEX DEC 
$EB 235 
$EC 236 
$ED 237 
SEE 238 
SEF 239 
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Code Meaning 


BAD NAME — The specified device, file, or mod- 
ule name is illegal. 


BAD MODULE HEADER — The specified mod- 
ule header parity is incorrect. 


RAM FULL — No free system random access 
memory is available: the system address space is 
full, or there is no physical memory available 
when requested by the operating system in the 
system state. 


UNKNOWN PROCESS ID — The specified pro- 
cess ID number is incorrect. 


NO TASK NUMBER AVAILABLE — All avail- 
able task numbers are in use. 


Device Driver Errors 


I/O device drivers generate the following error codes. In most 
cases, the codes are hardware-dependent. Consult your device 
manual for more details. 


Code 
HEX DEC 
$FO 240 
$F1 241 
$F2 242 
$F3 243 
$F4 244 


Code Meaning 


UNIT ERROR — The specified device unit 
doesn’t exist. 


SECTOR ERROR — The specified sector number 
is out of range. 


WRITE PROTECT — The specified device is 
write-protected. 


CRC ERROR — A Cyclic Redundancy Code error 
occurred on a read or write verify. 


READ ERROR — A data transfer error occurred 
during a disk read operation, or there is a SCF 
(terminal) input buffer overrun. | 
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Code 
HEX DEC 
$F5 2465 
$F6 246 
$F7 247 
$F8 248 
$F9 249 
SFA 250 
$FB 251 
$FC 252 
$FD 253 
$FE 254 
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Code Meaning 


WRITE ERROR — An error occurred during a 
write operation. 


NOT READY — The device specified has a not 
ready status. 


SEEK ERROR — The system attempted a seek 
operation on a non-existent sector. 


MEDIA FULL — The specified media has insuf- 
ficient free space for the operation. 


WRONG TYPE — An attempt is made to read 
incompatible media (for instance an attempt to 
read double-side disk on single-side drive). 


DEVICE BUSY — A non-shareable device is in 
use. 


DISK ID CHANGE — You changed diskettes 
when one or more files are open. 


RECORD IS LOCKED-OUT — Another process 
is accessing the requested record. 


NON-SHAREABLE FILE BUSY — Another pro- 
cess is accessing the requested file. 


T/O DEADLOCK ERROR — Two processes have 
attempted to gain control of the same disk area 
at the same time. 


Index 


ACIAPAK 8-135 

active process 2-12 - 2-13 
queue 2-14, 8-98 
state 2-13 - 2-14 


address 
find 64K block 8-85 
lines 2-7 


polling 2-17 
space, add module 8-104 
age, process 2-14 
alarm, set 8-66 
allocate 
high RAM 8-69 
image 8-70 
memory 8-76 
memory blocks 8-67 - 
8-68 
process descriptor 8-71 
process task number 
8-73 
RAM 8-72 
allocation 
bit map 8-7 
map sector 5-1 
of memory 2-5 - 2-7 
polling 2-17 
allocation map 


clear 8-13 

disk 5-3 
alpha screen 

cursor 8-118 

memory 8-117 
ASM assembler 8-2 
assembler, RMA 8-2 
attach a device 8-44 - 8-45 
attribute 

byte 5-5, 

file 5-12 


background color, get 8-129 
bell, set alarm 8-66 
bit map 2-5 

allocation 8-7 


bit map (cont’d.) 
search memory 
allocation 8-33 
block 
allocate system 
memory 8-105 
deallocate system 
memory 8-106 
map into process 
space 8-96 
number 2-7 
scroll 8-139 
block map, system 8-18 
boot 
file, load 5-26 
module, link 8-75 
booting OS-9 1-3 
bootstrap 
memory request 8-76 
system 8-75 
border color, get 8-129 
buffer 
map (Get/Put) 8-138 
reserve graphics 8-136 
button 
state, mouse 8-124 - 
8-125, 8-126 
timeout, mouse 8-140 
byte 
attribute 5-5 
deallocate 64-byte 
block 8-101 
get from memory 
block 8-94 
get two bytes 8-95 
read from path 8-59 - 
8-60 
store in task 8-109 


calling process 
insert in I/O queue 8-91 
terminate 8-14 
turn off 8-35, 8-43 
CC3DISK 1-2 
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CC3GO module 2-19 


CC3IO_ 1-2, 6-1 
chain 8-8 - 8-9 
change 


device operating 
parameters 5-23 
directory 8-46 
character 
read SCF input 6-13 
write, SCF 6-14 
ChgDir 4-4 
child process 2-13 
create 8-15 - 8-17 
clear specified block 8-77 
click 8-126 
CLOCK 1-2 
clock 
module 1-2, 2-19 
real-time 2-12, 2-17 
close 
file 4-7 
path 8-47, 8-135 
codes 
signal 2-15 
system error C-1l 
command interpreter 1-4 
communication, 
interprocess 2-15 
compact module directory 
8-88 
compare strings 8-10 
compatibility with Level 
One 2-1 
concurrent execution 7-1 - 7-3 
copy external memory 8-11 
count, link 2-5 
counter start, mouse 8-124 
CPU 2-7 
time 4-11 
CRC 
calculate 8-12 
validate module 8-111 
value 3-1 - 3-3 
create 
directory 8-55 - 8-56 


create (cont’d.) 
file 8-48 - 8-49 
current 
data directory 8-51 
execution directory 8-51 
cursor positioning 4-5 
cyclic redundancy check 3-1 - 


DAT 
hardware 8-99 
registers 8-103 
to logical address 8-78 
data 
available, SCF test 
8-113 
directory 8-51 
stream 4-3 
transfer, pipes 7-1 - 7-3 
move in memory 8-97 
DAT image 8-70 
conversion 8-78 
copy into process 
descriptor 8-102 
deallocate block 8-77 
high block 8-86 
low block 8-87 
pointer 8-95 
DAT task number 
release 8-99 
reserve 8-100 
date 
get system 8-40 
set 8-38 
deadlock 5-13 
deadly embrace 5-13 
deallocate 
image RAM blocks 8-79 
map bits 8-13 
process descriptor 8-80 
RAM blocks 8-81 
task number 8-82 
default palette registers 
8-129, 8-149 
delete file 8-50 - 8-51 


descriptions, system call 8-2 
descriptor 
get process 8-20 
path 4-18 
pointer 8-82 
process 2-13 
detach device 8-52 
device 
add or remove from 
polling table 8-92 
attach 8-44 - 8-45 
attachment, verify 


8-44 


controller 5-15 

control registers, 
initialize 6-12 

control registers, SCF 
6-12 

descriptor 1-4, 4-2, 4-17, 
A-2 

detach 8-52 

modules 5-15 

modules, RBF 5-8 - 5-10 

modules, SCF 6-6 - 6-8 

name, get 8-115 

open path to 8-57 - 8-58 

operating parameters, 
RBF 5-23 

operating parameters, 
SCF 6-15 

status 2-17 - 2-18, 8-63 

status, get 8-54 

table 4-2, 8-52 

terminate, RBF 5-24 

terminate, SCF 6-16 

write to 8-64 - 8-65 

device driver 1-3, 4-11 

close path 8-135 

modules 4-8 

name 5-15 


SCF 6-9 - 6-17 

SCF subroutines 6-10 - 
6-17 

subroutines, RBF 5-16 - 
5-27 


Index 


device driver modules, 
RBF 5-13 - 5-17 
device interrupt 5-25 
SCF 6-17 
directory 
attribute byte 5-5 
change 8-46 
disk 5-5 
entry, module 8-83 
get module 8-19 
make 8-55 - 8-56 
module 2-12, 8-88 
disk 
directories 5-5 
sector read 5-19, 5-21 
disk allocation map 5-3 
sector 5-1 
diskette format B-1 
display 
screen 8-143 
status, get 8-115 
drag 8-126 
drive head, restore 8-131 
duplicate path 8-53 


editing, line 6-1, 8-61 
end-of-file, test for 8-114 
equate file 2-4 
equivalent logical address 
8-78 
error 
- codes, system C-1 - C-6 
message, write 8-30 
print 8-30 
exclamation point, pipes 7-1 - 
7-3 
execute 
mode 5-11 
system calls 8-1 - 8-2 
execution 
directory 8-51 
offset, module 3-7 
exit calling process 8-14 
external memory, read 8-11 
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fatal signal 2-13 

file 
attribute byte 5-12 
closing 4-7 
create 4-4, 5-12, 8-48 - 

8-49 
deadlock 5-13 
delete 4-5, 8-50 - 8-51 
descriptor 5-3 - 5-4 
execute mode 5-11 
get pointer position 
-114 

line reading/writing 4-6 
load module 8-29 
locking 5-12 
non-shareable 
opening 4-4 
open path 8-57 - 8-58 
permission bits 5-4 
pipe 7-1 - 7-3 
pointer 4-5, 8-62 
position, RBF 8-114 
read 5-1, 4-5 
sharing 5-12 
size, get 8-114 
status, get 8-54, 8-114 
update mode 5-11 
write line to 8-64 - 8-65 
writing 4-6 

file manager 1-3 
modules 4-3 
name 5-15 

find 


5-12 


64-byte block 8-85 
module directory 
entry 8-84 

fire button 8-123 - 8-127 
FIRQ 4-12 

interrupt 2-17 
flag, RAM In Use 8-81 
flip byte 2-17 
floppy diskette format B-1 
foreground color, get 8-129 
FORK 2-8 
fork, child process 8-15 - 8-17 


FORMAT 5-2 
format 
device descriptor 4-17, 
A-2 
INIT module A-3 
memory module 3-6 - 
3-7, A-1 
of device driver 
modules 4-10 
track 8-132 
function 
calls 2-4 - 2-5, 8-1 
key sense 8-133 


get 
abyte 8-94 
free high block 8-86 
free low block 8-87 
ID 8-22 
process pointer 8-89 
status 8-54 
Status system calls 
8-112 - 8-130 
system time 8-40 
Get/Put buffer, map 8-138 
GETSTA 8-112 
SCF 6-15 
GetStat 4-6 
Getstats 5-23 
graphics buffer 
reserve 8-136 
select 8-137 
graphics interface 1-2 
GRFINT 1-2 


handler routine, virtual 
interrupt 8-110 

hard disk shutdown 8-133 

hardware 
controller, SCF 6-9 
DAT registers 8-103 
vector 2-16 

header 
module 3-1 - 3-2 
parity 8-111 


Index 


header (cont’d.) 
pattern, floppy 
diskette B-1 
high block, memory search 
8-86 
high-level 
menu handler 8-122 
menu manager 8-148 
window handler 8-139 
high-resolution 
mouse adapter 8-126 
screen, allocate 8-142 
hold, button 8-126 
1/O 
calls 2-4 - 2-5, 8-1 
device accessing 2-11 
module, delete 8-90 
path, close 8-47 
queue, insert calling 
process 8-91 
I/O system 1-3 - 1-4 
calls 2-1, 8-2 
system modules 
1-4, 4-1 
transfers 4-8 


1-1 - 


ID 
return caller’s 
process 8-22 
set user 8-39 
identification sector 5-1 
image, allocate 8-70 
INIT 1-2, 5-18 
INIT module 2-17 
format A-3 
link 8-75 
Init, SFC 6-12 
initialization table, SCF 
device 6-6 - 6-8 
initialize device memory 5-18 
input buffer, read SCF 
character 6-13 
insert process 8-74 
install virtual interrupt 
8-110 
intercept, set signal 8-21 


interface 
graphics 
VDG 4-2 
Windint 4-2 
interprocess 
communication 2-15 
interrupt 
device 5-25 
enable, SCF 6-12 
FIRQ 2-17 
processing 2-1 
IOMAN 1-2 
IRQ 4-12 
add/remove device from 
polling table 8-92 
interrupt 2-17 
polling 2-17 
polling table 2-18 
service routine 5-25 
IRQSVC routine 4-13 
IRQSV 4-11 


1-2 


joystick value, get 8-116 


kernel 1-2 
key 
repeat parameters, 
set 8-147 
sense function 8-133 
status, get 8-120 
keyboard scan 2-17 


language byte 3-4 
line 
editing 6-1, 8-61 
reads 4-6, 8-61 
writes 4-6, 8-65 
link 
to memory module 8-23 
- 8-24, 8-28 
using module directory 
entry 8-83 
link count 2-5 
decrease 8-42 
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load 
boot file 5-26 
byte from memory 
block 8-94 
from task offset 8-93 
module 8-25 - 8-26, 8-29 
two bytes 8-95 
lock, end-of-lock 5-12 


locking 

files 5-12 

record 5-10 - 5-11 
logical 


address space 2-6, 2-8 
sector number 5-1 
LSN_ 5-2, 5-5 


macro 2-4 
MAKDIR 4-4 
make directory 8-55 - 8-56 
manager 
file 1-3 
random block 1-3 
sequential file 1-3 
map 
block 8-96 
search allocation 8-33 
mask byte 2-18 
memory 
allocate 8-76 
allocate blocks 8-67 - 
8-68 
allocate high RAM 8-69 
change process data 
size 8-27 
deallocate 2-5 
find low block 8-87 
free screen 8-144 
map 2-6 
module format 3-6 - 3-7, 
A-1 
module, link 8-23 - 8-24 
move data 8-97 
page 2-5 
pool 8-80 
request, bootstrap 8-76 


memory (cont’d.) 
segment 2-8 
memory allocation 2-5 - 2-7 
memory block 2-7 
find 64K 8-85 
get byte 8-94 
get high 8-86 
map 8-81 
map, search 8-72 
memory management 2-1, 2-5 
- 2-12 
unit 2-7 - 2-8 
menu 
manager, update 
request 8-148 
selection 8-122 
message, write error 8-30 
MMU registers 2-8 
mnemonic name, LSN 
MODPAK 8-135 
module 
add into address 
space 8-104 
body 3-1 - 3-2 
clock 2-19 
CRC calculate 8-12 
decrease link count 8-42 
delete I/O module 8-90 
device descriptor 5-15 
device driver 4-8 
file manager 4-3 
finding 2-12 
format 3-1 - 3-3 
link 8-28 
link count, decrease 
8-42 
linking 1-2 
load 8-25 - 8-26, 8-29 
load and execute 
primary 8-8 - 8-9 
name 3-3 
RBF-type device 
drivers 5-13 - 5-17 
SCF device descriptor 
6-6 - 6-8 


5-2 


Index 


module (cont’d.) 
types 3-1, 3-5 
unlink 8-41 
validate 8-111 
module directory 2-5, 2-12 
compact 8-88 
entry, link using 8-83 
find 8-84 
get 8-19 
pointer 8-84 
module header 3-1 - 3-3, 5-15 
SCF device driver 6-9 
monitor, set type 8-146 
mouse 
button state 8-125 
button timeout 8-140 
click 8-122 
coordinates 8-127 
countdown 8-125 
countup 8-125 
parameters, set 8-147 
port 8-125 
resolution 8-126 
screen position 8-126 
send signal to process 8- 
1 


status, get 8-123 
timeout 8-124 
window working area 
8-127 
move data 8-97 
multiplexer 2-8 
multiprogramming 2-12 - 
2-16 
management 2-1 
multitasking 1-2 


name parse 8-31 - 8-32 
names, compare 8-10 
next process 8-98 

NMI interrupt 2-17 
non-shareable file 5-12 
number, path 8-53 


open 
file 8-48 - 8-49 
path 8-57 - 8-58 
operation of memory 
management 2-8 - 2-12 
OS-9 
Level One 
compatibility 2-1 
modules 1-2 
scheduler 2-14 - 2-15 
OS9P3 2-1 
module 2-2 


packet size 8-124 
palette, get information 8-127 
palette register 8-129 
set default 8-149 
settings 8-129 
parameters, mouse and key 
repeat 8-147 
parent 
directory 5-3 
process 2-13 
parity 8-135 
parse name 8-31 - 8-32 
path 
close 8-47, 8-135 
duplicate 8-53 
open 8-57 - 8-58 
read bytes 8-59 - 8-60 
table 4-2 
path descriptor 4-18, 5-5 - 
5-8 


read option section 
8-112 
SCF 6-2 - 6-6 
write option section 
8-130 
permanent storage size, 
module 3-7 
physical address space 2-7 
pipe file manager 4-3 
PIPEMAN 1-2 - 1-3, 4-3 
pipes 4-3, 7-1 - 7-3 
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process descriptor 2-13 - 
2-14, 8-102 
deallocate 8-80 
descriptor, allocate 8-71 
get 8-20 
pointer 8-82 
processes 
active 2-12 
data size, change 8-27 
process ID 2-13 
return caller’s 8-22 
pseudo vector 2-16 
PutStat 4-6 


RAM 2-5 - 2-7 
allocate 8-69, 8-72 
allocate blocks 8-70 
allocation 2-13 
blocks, deallocate 8-81 
blocks, deallocate 
image 8-79 
interrupt vector 2-18 
random 
access 9-1 
block file manager 1-3, 
4-3 
RBF 
change file size 8-131 
format track 8-132 
get file size 8-114 
manager 4-3 
tables 5-14 - 5-17 
read 
bytes 8-59 - 8-60 
device operating 
parameters 5-23 
disk sector 5-19 
external memory 8-11 
input character, SCF 
6-13 
line 6-2, 8-61 
mode 5-11 
system call 6-1 
real-time clock 2-12, 2-17 
record locking 5-10 


reference 
System Mode calls 8-5 - 
8-6 
User Mode system 
calls 8-3 - 8-4 
registers 
DAT 8-103 
MMU 2-8 
release a task 8-99 
request system memory 
8-105 
reserved memory 2-5 - 2-7 
reserve task number 8-100 
return 
64 bytes 8-101 
system memory 8-106 
RMA assembler 8-2 
ROOT directory 5-3, 5-5 
RTS instruction 2-18 


SCF 
configure serial port 
8-134 - 8-135 
data available test 
8-113 
device control 
registers 6-12 
Getsta 6-15 
manager 4-3 
path descriptor 6-2 - 6-6 
terminate device 6-16 
scheduler, OS-9 2-14 - 2-15 
screen 
allocate high- 
resolution 8-142 
convert type 8-145 
display 8-143 
free memory 8-144 
mouse position 8-126 
palette 8-127 
size, get 8-119 
type 8-128, 8-142, 8-145 
scroll block, install 8-139 
search bits 8-33 


Index 


sector 5-3 
pattern, floppy 
diskette B-1 
seek, file pointer 8-62 
segment, memory 2-8 
select graphics buffer 8-137 
send signal 8-34 
sequential character 
file manager 1-3, 4-3 
VO 6-1 
serial port configuration 
8-121 
service 
request processing 2-1 
routine, IRQ 5-25 
set 
alarm 8-66 
date 8-38 
TRQ 8-92 
priority 8-36 
process DAT image 
8-102 
process task DAT 
registers 8-103 
status 8-63 
SVC 8-107 - 8-108 
SWI 8-37 
time 8-38 
user ID 8-39 
Setstats 5-23 
Set Status system calls 8-130 
- 8-150 
shareable bit 3-5 
sharing, file 5-12 
shell 1-4 
shutdown hard disk 8-133 
signal 2-15 - 2-16 
codes 2-15 
fatal 2-13 
from mouse to 
process 8-141 
intercept trap 2-15 - 
2-16 
intercept, set 8-21 
send to process 8-34 


single-user 

attribute 5-12 

bit, files 5-12 
size 

of screen 8-119 

of window 8-119 
sleep 

calling process 8-35 
sleeping process 2-14, 2-16 
slices, time 2-12 
sound, create 8-150 
speaker, create sound 8-150 
state 

active 2-13 

of button 8-126 

sleeping 2-14 

suspend 4-13 

waiting 2-13 
static storage address 2-18 
status 

display 8-115 

get, SCF 6-15 

get mouse 8-123 - 8-127 

of key 8-120 

register 2-17 

set, SCF 6-15 
status, get 8-54 
status, set 8-63 
store byte in atask 8-109 
string, scan input 8-31 - 8-32 
strings, compare 8-10 
subroutines 

RBF device driver 5-16 - 

5-27 
SCF device drivers 6-10 
- 6-17 

suspend 

bit 4-13 - 4-14 

state 4-13 
SWI, set 8-37 
SWI2 instruction 2-4 
symbolic names 2-4 
sync byte 3-3 
synonymous path number, 

return 8-53 
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system 
block map, get 8-18 
boot 1-3 


bootstrap 8-75 
date, get 8-40 
device, attach 8-44 
error codes C-1 - C-6 
initialization 2-1 
link 8-104 
mode call reference 8-5 - 
8-6 
time, get 8-40 
system call 
add 8-107 - 8-108 
descriptions 8-2, 2-4 
execution 8-1 - 8-2 
get status 8-112 - 8-130 
mnemonics names 8-1 
User Mode reference 8-3 
- 8-4 
system memory 
allocate high RAM 8-69 
block map 8-81 
deallocate 8-106 
module directory, get 
8-19 
request 8-105 
system modules 1-1 - 1-4 


table 
device 8-52 
IRQ polling 2-18 
RBF 5-14 - 5-17 
SCF device descriptor 
6-6 - 6-8 
VIRQ 2-20 
task 
' map 2-12 
offset, load from 8-93 
register 2-8 
release 8-99 
store byte 8-109 
task number 8-73 
DAT 8-100 
deallocate 8-82 
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terminal, create sound 8-150 
terminate 
a device 5-24 
calling process 8-14 
SCF device 6-16 
ticks 4-11 
time 
CPU 4-11 
get system 8-40 
set 8-38 
sharing 2-11 
slice 2-16, 2-12 
timeout, mouse 8-124 
track 
format 8-132 
restore drive head 8-131 
trailer pattern, floppy 
diskette B-1 
trap, signal intercept 2-15 - 
2-16 
type 
convert screen 8-145 
of screen 8-128 
set monitor 8-146 
window screen 8-142 


unlink module 8-41 - 8-42 
update mode 5-11 
user calls 2-5 
user ID 2-13 
set 8-39 
User Mode system calls 
reference 8-3 - 8-4 


validate module 8-111 
VDG 1-2 
alpha screen cursor 
8-118 
alpha screen memory 
8-117 
interface 4-2 
vector 
pseudo 2-16 
set SWI 8-37 
vectoring 2-16 


verify device attachment 
8-44 - 8-45 
video display generator 1-2 
VIRQ 2-19 - 2-20 
polling table 2-19 - 2-20 
virtual interrupt, install 
8-110 


wait 
calling process 8-43 
state 2-13 - 2-14 
waiting process 2-13 
wildcard 4-6 


WINDINT 1-2 
Windint interface 4-2 
window 


descriptors 1-2 

high-level handler 8-139 

pointer location 8-124 

screen, type 8-142 

size, get 8-119 

type 8-145 

working area, mouse 
8-127 


Index 


working directory, change 
8-46 
write 
character to SCF 
output 6-14 
disk sector 5-21 
path descriptor 8-130 - 
8-131 
to file or device 8-64 
write line 8-65 
line system call 6-2 
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Chapter 1 


Types of OS-9 Windows 


Unlike many operating systems, OS-9 has a built-in windows 
program. This driver, the Windowing System, lets you lay one or 
more smaller screen displays, called windows, on your screen 
display. 


With these windows, you can perform several tasks at the same 
time. For example, suppose you are writing a business letter 
using a word processor in one window. You can go to a spread- 
sheet program in another window, get a price quote you need, 
return to the word processor, and include the price in the letter. 


The Windowing System allows as many windows as your com- 
puter’s memory can support, with a maximum of 32 at one time. 


In OS-9, there are two types of windows: device and overlay. 


Device Windows 


A device window is one that can run a program or utility. This 
is the type of window you would use in the word processor/ 
spreadsheet example given above. Each device window acts as an 
individual terminal. 


The device windows are designated as devices /wl - /w7. You 
open a device window as you do any other OS-9 device. You tell 
OS-9 the window’s parameters—including whether the window is 
for text or graphics. If you want to run a process in the window, 
you can start an execution environment, such as a shell, on the 
window. (See “Opening a Device Window,” later in this chapter, 
and the DWSet command in Chapter 3.) 


Note: If you want only to send output to the device win- 
dow—without running a process in the window—do not 
start a shell on the window. 


Device windows cannot overlay each other, and their boundaries 
cannot overlap. 
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Overlay Windows 


An overlay window is a window that you open on top of a device 
window. (You can place overlay windows over other overlay win- 
dows, but there must always be a device window at the bottom of 
the stack.) The purpose of overlay windows is to display com- 
puter dialog. You cannot fork a shell to an overlay window; how- 
ever, you can run a shell in an overlay window. Overlay windows 
assume the screen type of the device windows they overlay. 


Opening a Device Window 


To open a device window, follow these steps: 


Li 


If you want to allocate memory for the window, use OS-9’s 
iniz command. Type: 


iniz /wnumber | ENTER 


where number is the number of the device window you wish 
to open (1-7). If you do not specify number, OS-9 uses the 
next available device window number. 


If you do not use the iniz command, memory is allocated 
dynamically (as needed) to the window. 


Next, you send an escape sequence to OS-9 that tells it the 
window’s parameters. These parameters include the screen 
type, size, and colors. For example: 


wereate /w -s=2 20 180 49 10 01 @@ @@O | ENTER 
or 


display 1b 20 82 14 Ba 28 Ba 01 OB BB /w 


sends the escape sequence for the next available window to 
the DWSet command. The wcreate command lets you use 
decimal numbers, while the display command requires 
hexadecimal numbers. 
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If you wish to send an escape sequence to a specific win- 
dow, route the command to that device. For example: 


wereate /w2 -s=2 20 19 40 10 01 @@ Q@ (ENTER) 


sends the escape sequence to device /w2. The functions of 
the codes, as used in the wereate command, are as follows: 


2 sets a screen type of 80 x 24 (text only). 


20 starts the window at character/column 20. 
10 starts the window at line/row 10. 

40 sets a window size of 40 characters. 

10 sets a window size of 10 lines. 

01 sets the foreground color to blue. 


00 sets the background color to white. 
00 sets the border to white. 


If you do not send escape sequences, OS-9 uses default 
descriptors for the windows. The defaults are: 


Size 
Window Screen Type Starting Position (columns, 
Number (chars./line) (horiz., vert.) rows) 
1 40 (text) 0,0 Bik 
2 40 (text) 28,0 12,11 
3 40 (text) 0,12 40,12 
4 80 (text) 0,0 60,11 
5 80 (text) 60,0 19,11 
6 80 (text) 80,0 80,12 
t 80 (text) 0,0 80,24 


Use OS-9’s shell command to fork a shell to the window. 
Type: 


shell i=/wnumber & [ENTER 


where number is the number used in the iniz or wcreate 
command. The i= parameter creates an immortal shell. 
Creating an immortal shell protects the window and its 
shell from being destroyed if you accidentally exit the shell 
using (CTRL)(BREAK}. If you omit the i= parameter, the shell 
is forked to the next available device window. 


You now have a window that can run its own tasks. Information 
displayed in that window is automatically scaled to the window’s 
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Opening an Overlay Window 


To open an overlay window, use the Overlay Window Set func- 
tion. (See OWSet in Chapter 3, “General Commands.”) 
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Chapter 2 


Overview of Commands and 
Parameters 


The windowing commands are divided among three chapters, 
based on their functions. 


Chapter 3 describes the general commands. These commands let 
you create windows and buffers, access buffers, set switches, and 
maintain the window environment. 


Chapter 4 describes the drawing commands. Besides letting you 
draw all kinds of images (circles, ellipses, arcs, and boxes, to 
name a few), these commands also enable you to color areas or to 
fill them with patterns. 


Chapter 5 describes the text commands. Use these commands to 
manipulate the text cursor and the text attributes. Text com- 
mands operate on hardware text screens (Screen Types 1 and 2) 
and graphics windows if a font is selected. 


Each command description lists the command’s name, code, and 
parameters. To call a Windowing System command using OS-9’s 
display command, type display, followed by the command code 
and the values you want to supply for the parameters. 


Parameters 


The following is a complete list of the parameter abbreviations 
used in Chapters 3, 4, and 5. All parameters represent a single 
byte of information. 


Parameter Description 

HBX high order byte of x value 

LBX low order byte of x value 

HBY high order byte of y value 

LBX low order byte of y value 

HBXo high order byte of x-offset value (relative) 
LBXo low order byte of x-offset value (relative) 
HBYo high order byte of y-offset value (relative) 
LBYo low order byte of y-offset value (relative) 
HBR high order byte of radius 

LBR low order byte of radius 
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Parameter 


HBL 
LBL 


HSX 
LSX 
HSY 
LSY 


HBRx 
LBRx 


GRP 
BFN 
LCN 
PRN 
CTN 
FNM 
CPX 
CrY 
STY 
SVS 


SZX 
SZY 
XDR 


YDR 
BSW 


Description 


high order byte of length 
low order byte of length 


high order byte of size in x direction 
low order byte of size in x direction 
high order byte of size in y direction 
low order byte of size in y direction 


high order byte of radius in x direction 
low order byte of radius in x direction 


GET/PUT buffer group number (1-254) 
GET/PUT buffer number (1-255) 

logic code number 

palette register number (0-15, wraps mod 15) 
color table number (0-63, wraps mod 64) 

font number 

character position x (O0-xmax) 

character position y (O-ymax) 

screen type 

save switch (0=nosave, 1=save area under 
overlay) 

size in x (columns) 

size in y (rows) 

dimension ratio x used with YDR as YDR/ 
XDR 

dimension ratio y 

binary switch (0 = off, 1=on) 


Chapter 3 


General Commands 


The general commands let you set up and customize windows. 
They also let you set up and access image buffers and select 
colors for the screen. 
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BColor Background Color 


Function: Lets you choose a color palette register to use as the 
background color. See the Palette command for setting up the 
actual colors. 


Code: 1B 33 


Parameters: PRN 
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BoldSw Bold Switch 


Function: Enables or disables boldfacing for text on graphics 
screens. If boldface is on, the screen displays subsequent char- 
acters in bold. If boldface is off, the screen displays subsequent 
characters in the regular font. 


Code: 1B 3D 


Parameters: BSW 


BSW = switch 
00 = off (Default) 
O01 on 


Notes: 
@ You can use BoldSw with any font. 


@ Boldface is not supported on hardware text screens (Screen 
Types 1 and 2). 
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Border Border Color 


Function: Lets you change the palette register used for the 
screen border. See the Palette command for setting up the 
actual colors. 


Code: 1B 34 
Parameters: PRN 


Notes: 


@ You set the border by selecting a palette register to use for 
the border register. When the actual color is changed in the 
palette register selected by the command, the color of the 
screen border changes to the new color. In general, the bor- 
der register usually matches the background palette 
register. 
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CWArea Change Working Area 


Function: Lets you alter the working area of the window. Nor- 
mally, the system uses this call for high-level windowing, but 
you can use it to restrict output to a smaller area of the win- 
dow. 


Code: 1B 25 
Parameters: CPX CPY SZX SZY 
Notes: 


@ You cannot change a window’s working area to be larger 
than the predefined area of the window as set by DWSet or 
OWSet. 


e All drawing and window updating commands are done on 
the current working area of a window. The working area 
defaults to the entire size of the window. Scaling, when in 
use, is also performed relative to the current working area 
of a window. The CWArea command allows users to restrict 
the working area of a window to smaller than the full win- 
dow size. Functions which might be done by opening a non- 
saved overlay window to draw or clear an image and then 
closing the overlay can be accomplished by using this com- 
mand to shorten execution time where an actual overlay 
window is not needed. 
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DefC olr Default Color 


Function: Sets the palette registers back to their default val- 
ues. The actual values of the palette registers depend on the 


type of monitor you are using. (See montype in OS-9 Level 
Two Commands.) 


Code: 1B 30 
Parameters: None 


Notes: 


@ The default color definitions apply only to high-resolution 
graphics and text displays. 


@ The system sets the palette registers to a proper compati- 
bility mode when switching to screens using the older VDG 
emulation modes. See the table below: 


Window System 


Color Modes VDG-Compatible Modes 


Palette Color P# Color P# Color 
00 & 08 White 00 Green 08 Black 
01 & 09 Blue 01 Yellow 09 Green 
02 & 10 Black 02 Blue OA Black 
03 & 11 Green 03 Red OB Buff 
04 & 12 Red 04 Buff OC Black 
05 & 13 Yellow 05 Cyan OD Green 
06 & 14 Magenta 06 Magenta OE Black 
07 & 15 Cyan 07 Orange OF Orange 


@ The SetStat call lets you change the default color palette 
definition when using the windowing system. Default colors 
in the VDG-Compatible Mode cannot be changed. See the 
OS-9 Level Two Technical Reference manual for information 
on SetStat. 


® The system’s default colors are used whenever you create a 
new window. 
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DfnGPBuf Define GET/PUT Buffer 


Function: Lets you define the size of the GET/PUT buffers for 
the system. Once you allocate a GET/PUT buffer, it remains 
allocated until you use the KilBuf command to delete it. 


OS-9 allocates memory for GET/PUT buffers in 8K blocks that 
are then divided into the different GET/PUT buffers. Buffers 
are divided into buffer groups. Therefore, all commands deal- 
ing with GET/PUT buffers must specify both a group number 
and a buffer number within that group. 


Code: 


1B 29 


Parameters: GRP BFN HBL LBL 


Technical: 


The buffer usage map is as follows: 


Group Buffer 


Number Number! Use 


1-255 Internal use only (returns errors) 


1 - 199 1-255 General use by applications? 


200 - 


254 1-255 Reserved (Microware use only)? 


255 1-255 Internal use only (returns errors) 


1 
2 


ve) 


Buffer Number 0 is invalid and cannot be used. 

The application program should request its user ID via 
the GetID system call to use as its group number for 
buffer allocation. 

The standard group numbers are defined as follows: 


Note: The names, buffer groups, and buffer numbers are 
defined in the assembly definition file. The decimal num- 
ber you use to call these are in parentheses next to the 
name. For example, to select the Arrow pointer, 
Grp—Ptr and Ptr_Arr, you use 202,1 as the group/buffer 
number. 
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Grp_Fnt(200) = font group for system fonts 
Fnt_S8x8(1) = standard 8x8 font 
Fnt_S6x8(2) = standard 6x8 font 
Fnt_G8x8(3) = standard graphics font 


The standard fonts are in the file SYS/ 
StdFonts. 


Grp—Clip(201) = clipboarding group (for Multiview) 


Grp_Ptr(202) = graphics cursor (pointer) group 
Ptr_Arr(1) = arrow pointer (hp =0,0) 
Ptr_Pen(2) = pencil pointer (hp =0,0) 
Ptr_LCH(3) = large cross hair pointer 


(hp = 7,7) 
Ptr_Slp(4) = sleep indicator (hourglass) 
Ptr—TIll(5) = illegal indicator 


Ptr_Txt(6) = text pointer (hp =3,3) 
Ptr_SCH(7) =small cross hair pointer 
(hp = 3,3) 


hp = hit point, the coordinates 
of the actual point on the 
object at which the cursor 
should be centered. 


The standard pointers are in the file SYS/ 
StdPtrs. 


Grp_Pat2(203) =two color patterns 

Grp_Pat4(204) = four color patterns 

Grp—Pat6(205) = sixteen color patterns 
Pat_Dot(1) = dot pattern 
Pat_Vrt(2) = vertical line pattern 
Pat_Hrz(3) = horizontal line pattern 
Pat_XHtc(4) = cross hatch pattern 
Pat_LSnt(5) left slanted lines 
Pat_RSnt(6) right slanted lines 
Pat_SDot(7) small dot pattern 
Pat__BDot(8) large dot pattern 


Each pattern is found within each of the 
pattern groups. 


Standard patterns are in the files 
SYS/StdPats_2, SYS/StdPats_4, and 
SYS/StdPats_16. 
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All files have GPLoad commands imbedded in file, along with 
the data. To load fonts, pointers, or patterns, simply merge them 
to any window device: For example: 


merge SYS/StdFonts 


sends the standard font to standard output which may be redi- 
rected to another device if the current output device is not a win- 
dow device (such as when term is a VDG screen). 


You only need to load fonts once for the entire system. Once a 
Get/Put buffer is loaded, it is available to all devices and pro- 
cesses in the system. 
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DWE nd Device Window End 


Function: Ends a current device window. DWEnd closes the 
display window. If the window was the last device window on 
the screen, DWEnd also deallocates the memory used by the 
window. If the window is an interactive window, OS-9 auto- 
matically switches you to a new device window, if one is 
available. 


Code: 1B 24 
Parameters: None 


Notes: 


@ DWEnd is only needed for windows that have been attached 
via the iniz utility or the I$Attach system call. Non- 
attached windows have an implied DWEnd command that is 
executed when you close the path. 
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DWP rotSw Device Window Protect Switch 


Function: Disables and enables device window protection. By 
default, device windows are protected so that you cannot over- 
lay them with other device windows. This type of protection 
helps avoid the possibility of destroying the contents of either 
or both windows. 


Code: 1B 36 
Parameters: BSW 
BSW = switch 
OG = air 


01 = on (Default) 
Notes: 


@ We recommend that you not turn off device window protec- 
tion. If you do, however, use extreme discretion because you 
might destroy the contents of the windows. OS-9 does not 
return an error if you request that a new window be placed 
over an area of the screen which is already in use by an 
unprotected window. 


OS-9 Windowing System 


DWSet Device Window Set 


Function: Lets you define a window’s size and location on the 
physical screen. Use DWSet after opening a path to a device 
window. 


Code: 1B 20 
Parameters: STY CPX CPY SZX SZY PRN1 PRN2 PRN3 


PRN1 = Foreground 
PRN2 = Background 
PRN3 = Border (if STY 2 1) 
Notes: 
e The iniz and display commands open paths to the device 
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window. 


When using DWSet in a program, you must first open the 
device. 


Output to a new window is ignored until OS-9 receives a 
DWSet command, unless defaults are present in the device 
descriptor (/wl-/w7). If defaults are present in the device 
descriptors, OS-9 automatically executes DWSet, using 
those defaults. 


When OS-9 receives the DWSet, it allocates memory for the 
window, and clears the window to the current background 
color. If the standard font is already in memory, OS-9 
assigns it as the default font. If the standard font is not in 
memory, you must execute a font set (Font) command after 
loading the fonts to produce text output on a graphics 
window. 


Use the Screen Type code (STY) to define the resolution 
and color mode of the new screen. If the screen type code is 
zero, OS-9 opens the window on the process’s currently 
selected screen. If the code is 01, OS-9 opens the window on 
the currently displayed screen. If the code is non-zero, OS-9 
allocates a new screen for the window. The following 
describes the acceptable screen types: 


Ww 
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Code Screen Size Colors Memory Type 
FF Current Displayed Screen! 


00 Process’s Current Screen 

01 40 x 24 8 & 8 2000 Text 

02 80 x 24 8 & 8 4000 Text 

05 640 x 192 2 16000 Graphics 
06 320 x 192 4 16000 Graphics 
07 640 x 192 4 32000 Graphics 
08 320 x 192 16 32000 Graphics 


1Use the Current Displayed Screen option only in proce- 
dure files to display several windows on the same physical 
screen. All programs should operate on that process’s cur- 
rent screen. 


The location of the window on the physical screen is deter- 
mined by the diagonal line defined by: 


(CPX,CPY) and (CPX +SZX, CPY +SZY) 


The foreground, background, and border register numbers 
(PRN1, PRN2, and PRN3) define the palette registers used 
for the foreground and background colors. See the Palette 
command in this chapter for more information. 


When an implicit or explicit DWSet command is done on a 
window, the window automatically clears to the background 
color. 


All windows on the screen must be of the same type (either 
text or graphics). 


Values in the palette register affect all windows on the 
screen. However, you can choose which register to use for 
foreground and background for each window. That is, OS-9 
maintains palette registers and border register numbers for 
the entire screen and foreground and background register 
numbers for each individual window. 


OS-9 deallocates memory for a screen when you terminate 
the last window on that screen. 
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FColor Foreground Color 


Function: Lets you select a color palette register for the fore- 
ground color. See the Palette command for setting the actual 
colors. 


Code: 1B 32 


Parameters: PRN 
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Font Select Font 


Function: Lets you select/change the current font. Before you 
can use this command, the font must be loaded into the speci- 
fied GET/PUT group and buffer (using GPLoad). See the 
GPLoad command for information on loading font buffers. 


Code: 1B 3A 
Parameters: GRP BFN 


Notes: 


@ You can select proportional spacing for the font by using 
PropSw. 


@ All font data is a 2-color bit map of the font. 


@ Each character in the font data consists of 8 bytes of data. 
The first byte defines the top scan line, the second byte 
defines the second scan line, and so on. The high-order bit 
of each byte defines the first pixel of the scan line, the next 
bit defines the next pixel, and so on. For example, the letter 
“A” would be represented like this: 


Byte Pixel Representation 
LO! ae ae ee GRR: ee He 
28 « & Ho. Hs 


Note that 6x8 fonts ignore the last 2 bits per byte. 


e The fonts are ordered with characters in the following 
ranges: 


$00-$1F International characters (see mapping below) 
$20-$7F Standard ASCII characters 
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International characters or any characters in the font below 
character $20 (hex) are printed according to the following 


table: 
Character position Charl or Char2 aad 
in font 
$00 $Cl1 $E1 
$01 $C2 $E2 
$02 $C3 $E3 
$03 $C4 $E4 
$04 $C5 $E5 
$05 $C6 $E6 
$06 $C7 $E7 
$07 $C8 $E8 
$08 $C9 SEQ 
$09 $CA SEA 
$0A $CB SEB 
$0B $CC SEC 
$0C $CD $ED 
$0D $CE $EE 
$0E $CF SEF 
$0F $D0 $FO Ww 
$10 $D1 $F 1 
$11 $D2 $F 2 
$12 $D3 $F3 
$13 $D4 $F4 
$14 $D5 $F5 
$15 $D6 $F6 
$16 $D7 $F7 
$17 $D8 $F8 
$18 $D9 $F9 
$19 $DA SFA 
$1A SAA $BA 
$1B $AB $BB 
$1C $AC $BC 
$1D $AD $BD 
$1E SAE $BE 
$1F SAF $BF 
WwW 
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GCSet Graphics Cursor Set 


Function: Creates a GET/PUT buffer for defining the graphics 
cursor that the system displays. You must use GCSet to dis- 
play a graphic cursor. 


Code: 1B 39 
Parameters: GRP BFN 
Notes: 


@ To turn off the graphics cursor specify GRP as 00. 


@ A system standard buffer or a user-defined buffer can be 
used for the graphics cursor. 
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GetBIK Get Block 


Function: Saves an area of the screen to a GET/PUT buffer. 
Once the block is saved, you can put it back in its original 
location or in another on the screen, using the PutBlk 
command. 


Code: 1B 2C 
Parameters: GRP BFN HBX LBX HBY LBY HSX LSX HSY 
LSY 


HBX/LBX = x-location of block (upper left corner) 
HBY/LBX = y-location of block 

HSX/LSX = x-dimension of block 

HSY/LSY = y-dimension of block 


Notes: 


@® The GET/PUT buffer maintains information on the size of 
the block stored in the buffer so that the PutBlk command 
works more automatically. 


@ If the GET/PUT buffer is not already defined, GetBlk cre- 
ates it. If the buffer is defined, the data must be equal to or 
smaller than the original size of the buffer. 
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GPLoad GET PUT Buffer Load 


Function: Preloads GET/PUT buffers with images that you 
can move to the screen later, using PutBlk. 


If the GET/PUT buffer is not already created, GPLoad creates 


Its 


If the buffer was previously created, the size of the passed 
data must be equal to or smaller than the original size of the 
buffer. Otherwise, GPLoad truncates the data to the size of 


the buffer. 
Code: 


Parameters: 


Notes: 


1B 2B 


GRP BFN STY HSX LSX HSY LSY HBL LBL 
(Data...) 


STY = format 

HSX/LSX = x-dimension of stored block 
HSY/LSY = y-dimension of stored block 
HBL/LBL = number of bytes in data 


e Buffers are maintained in a linked list system. 


e Buffers to be used most should be allocated last to mini- 
mize the search time in finding the buffers. 


@ When loading a Font GET/PUT Buffer, the parameters are 


as follows: 


GRP BFN STY HSX LSX HSY LSY HBL LBL 


(Data...) 
GRP = 254 
Sry = 5 


HSX/LSX = x-dimension size of Font 6 or 8 
HSY/LSY = y-dimension size of Font 8 

HBL/LBL = size of font data (not including this 
header information) 


See the Font command for more information on font data. 
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KilBuf kill GeT/PUT Buffer 


Function: Deallocates the buffer specified by the group and 
buffer number. To deallocate the entire group of buffers, set 
the buffer number to 0. 


Code: 1B 2A 
Parameters: GRP BFN 
Notes: 


e KilBuf returns memory used by the buffer to a free list. 
When an entire block of memory has been put on the free 
list, the block is returned to the system. 
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LSet Logic Set 


Function: Lets you create special effects by specifying the 
type of logic used when storing data, which represents an 
image, to memory. The specified logic code is used by all draw 
commands until you either choose a new logic or turn off the 
logic operation. To turn off the logic function, set the logic code 
to 00. 


Code: 1B 2F 


Parameters: LCN 


LCN = logic code number 
00 = No logic code; store new data on 
screen 
01 = AND new data with data on 
screen 
02 = OR new data with data on screen 


03 = XOR new data with data on screen 
Notes: 
e The following tables summarize logic operations in bit 
manipulations: 
AND First Second Result 
Operand Operand 
1 1 lL 
1 0) 0 
0 i 0 
0 0 0 
OR First Second Result 
Operand Operand 
1 i 1 
1 0 il 
0 Z 1 
0 0 0 
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XOR First Second Result 
Operand Operand 
1 1 0 
Z 0 1 
0 1 1 
0 0 0 


Data items are represented as palette register numbers in 
memory. Since logic is performed on the palette register 
number and not the colors in the registers, you should 
choose colors for palette registers carefully so that you 
obtain the desired results. You may want to choose the 
colors for the palette registers so that LSet appears to and, 
or, and xor the colors rather than the register numbers. For 
example: 


Palette # Color Alternative Order 
0 White Black 
1 Blue Blue 
2 Black Green 
3 Green White 
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OW End Overlay Window End 


Function: Ends a current overlay window. OWEnd closes the 
overlay window and deallocates memory used by the window. 
If you opened the window with a save switch value of hexadec- 
imal 01, OS-9 restores the area under the window. If you did 
not, OS-9 does not restore the area and any further output is 
sent to the next lower overlay window or to the device window, 
if no overlay window exists. 


Code: 1B 23 


Parameters: None 
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OWSet Overlay Window Set 


Function: Use OWSet to create an overlay window on an exist- 
ing device window. OS-9 reconfigures current device window 
paths to use a new area of the screen as the current logical 
device window. 


Code: 1B 22 
Parameters: SVS CPX CPY SZX SZY PRN1 PRN2 


SVS = save switch 
00 = Do not save area overlayed 
01 = Save area overlayed and restore at 
close 
PRN1 = background palette register 
PRN2 = foreground palette register 


Notes: 


e If you set SVS to zero, any writes to the new overlay win- 
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dow destroy the area under the window. You might want to 
set SVS to zero if your system is already using most of its 
available memory. You might also set SVS to zero whenever 
it takes relatively little time to redraw the area under the 
overlay window once it is closed. 


If you have ample memory, specify SVS as 1. Doing this 
causes the system to save the area under the new overlay 
window. The system restores the area when you terminate 
the new overlay window. (See OWEnd.) 


The size of the overlay window is specified in standard 
characters. Use the same resolution (number of characters) 
as the device window that will reside beneath the overlay 
window. Have your program determine the original size of 
the device window at startup (using the SS.ScSiz GETSTAT 
call), if the device window does not cover the entire screen. 
See the OS-9 Level Two Technical Reference manual for 
information on the SS.ScSiz GETSTAT call. 
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@ Overlay windows can be created on top of other overlay 
windows; however, you can only write to the top most win- 
dow. Overlay windows are “stacked” on top of each other 
logically. To get back down to a given overlay, you must 
close (OWEnd) any overlay windows that reside on top of 
the desired overlay window. 


@ Stacked overlay windows do not need to reside directly on 
top of underlying overlay windows. However, all overlay 
windows must reside within the boundaries of the underly- 
ing device window. 
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Palette Change Palette 


Function: Lets you change the color associated with each of 
the 16 palette registers. 


Code: 1B 31 
Parameters: PRN CTN 
Notes: 


@ Changing a palette register value causes all areas of the 
screen using that palette register to change to the new 
color. In addition, if the border is set to that palette regis- 
ter, the border color also changes. See the Border command 
for more information. 


e Colors are made up by setting the red, green, and blue bits 
in the color byte which is inserted in the palette register. 
The bits are laid out as follows: 


Bit Color 

Blue low 
Green low 
Red low 
Blue high 
Green high 
Red high 
unused 
unused 


ID oP CONF © 


By using six bits for color (2 each for red, green and blue) 
there is a possibility of 64 from which to choose. Some of 
the colors are defined as shown: 


White : 00111111 
Black : 00000000 = $00 (no color bits set) 
Standard Blue : 00001001 = $09 (both blue bits set) 
Standard Green : 00010010 = $12 (both green bits set) 
Standard Red : 00100100 = $24 (both red bits set) 


$3F (all color bits set) 


3-26 


General Commands / 3 


Note: These colors are for RGB monitors. The composite 
monitors use a different color coding and do not directly 
match pure RGB colors. To get composite color from the 
RGB colors, the system uses conversion tables. The colors 
were assigned to match the RGB colors as close as possible. 
There are, however, a wider range of composite colors, so 
the colors without direct matches were assigned to the clos- 
est possible match. The white, black, standard green, and 
standard orange are the same in both RGB and composite. 
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Prop Sw Proportional Switch 


Function: Enables and disables the automatic proportional 
spacing of characters. Normally, characters are not proportion- 
ally spaced. 


Code: 1B 3F 
Parameters: BSW 
BSW = switch 
00 = off (Default) 
Ol =-on 
Notes: 


e Any standard software font used in a graphics screen can 
be proportionally spaced. 


® Proportional spacing is not supported on hardware text 
screens. 
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P Set Pattern Set 


Function: Selects a preloaded GET/PUT buffer as a pattern 
RAM array. This pattern is used with all draw commands 
until you either change the pattern or turn it off by passing a 
parameter of 00 as GRP (Group Number). 


Code: 1B 2E 
Parameters: GRP BFN 
Notes: 


@ The pattern array is a 32 x 8 pixel representation of graph- 
ics memory. The color mode defines the number of bits per 
pixel and pixels per byte. So, be sure to take the current 
color mode into consideration when creating a pattern 
array. 


@ The GET/PUT buffer can be of any size, but only the num- 
ber of bytes as described by the following table are used: 


Color 
Mode Size of Pattern Array 
2 4 bytes x 8 = 32 bytes (1 bit per pixel) 
4 8 bytes x 8 = 64 bytes (2 bits per 
pixel) 
16 16 bytes x 8 = 128 bytes (4 bits per 
pixel) 


e The buffer must contain at least the number of bytes 
required by the current color mode. If the buffer is larger 
than required, the extra bytes are ignored. 


e To turn off patterning, set GRP to 00. 
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The following example creates a two color pattern of vertical 
lines. A two color pattern is made up of 1’s and 0’s. The 
diagram below shows the bit set pattern (note that one 
pixel is equal to one bit): 


10101010101010101010101010101010 
10101010101010101010101010101010 
10101010101010101010101010101010 
10101010101010101010101010101010 
10101010101010101010101010101010 
10101010101010101010101010101010 
10101010101010101010101010101010 
10101010101010101010101010101010 


When the binary for the 2x8 pixel data is compressed into 
byte data, notice that each row consists of 4 bytes of data. 
The pattern now looks like this: 


$55 $55 $55 $55 
$55 $55 $55 $55 
$55 $55 $55 $55 
$55 $55 $55 $55 $55 = 01010101 
$55 $55 $55 $55 
$55 $55 $55 $55 
$55 $55 $55 $55 
$55 $55 $55 $55 


To load the pattern in the system, use the GPLoad com- 
mand. To load this particular pattern into Group 2 and 
Buffer 1, the command would be: 


display 1b 2b 02 01 08 20 00 08 88 20:55 55: aiwne 
| | | 
32 times 
number of bytes (32) 
y size of pattern (8) 
x size of pattern (32) 
buffer number 


group number 
GPLoad code 
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@ When making a pattern using 4 colors, a pixel is made up 
of two bits instead of one. This means that the pattern con- 
sists of 64 bytes instead of 32. The diagram below shows 
the bit set pattern for the same vertical pattern using 4 
colors: 


1100110011001100110011001100110011001100110011001100110011001100 
1100110011001100110011001100110011001100110011001100110011001100 
1100110011001100110011001100110011001100110011001100110011001100 
1100110011001100110011001100110011001100110011001100110011001100 
1100110011001100110011001100110011001100110011001100110011001100 
1100110011001100110011001100110011001100110011001100110011001100 
1100110011001100110011001100110011001100110011001100110011001100 
1100110011001100110011001100110011001100110011001100110011001100 


When the binary for the 4x8 pixel data is compressed into 
byte data, notice that each row consists of 8 bytes of data. 
The pattern now looks like this: 


$CC $CC $CC $CC $CC $CC $CC $CC 
$CC $CC $CC $CC $CC $CC $CC $CC 
$CC $CC $CC $CC $CC $CC $CC $CC 
$CC $CC $CC $CC $CC $CC $CC $CC $CC = 1100 
$CC $CC $CC $CC $CC $CC $CC $CC 
$CC $CC $CC $CC $CC $CC $CC $CC 
$CC $CC $CC $CC $CC $CC $CC $CC 
$CC $CC $CC $CC $CC $CC $CC $CC 


To load the pattern in the system, use the GPLoad com- 
mand as described for the 2 color example but specify $40 
(64) bytes instead of $20 (32). 


@ When making a pattern using 16 colors, a pixel is made up 
of four bits instead of one. This means that the pattern con- 
sists of 128 bytes. Each line in the bit pattern would look 
like this: 


11110000...{repeat pattern for 16 total sets}...11110000 


When the binary for the 8x8 pixel data is compressed into 
byte data, the pattern is a series of $F0. 


To load the pattern in the system, use the GPLoad com- 
mand and specify $80 (128) bytes as the size. 
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PutBIk put Block 


Function: Moves a GET/PUT buffer, previously copied from the 
screen or loaded with GPLoad, to an area of the screen. 


Code: 1B 2D 


Parameters: GRP BFN HBX LBX HBY LBY 


HBX/LBX = x-location of block 
(upper left corner) 
HBY/LBY = y-location of block 


Notes: 


@ The dimensions of the block were saved in the GET/PUT 
buffer when you created it. OS-9 uses these dimensions 
when restoring the buffer. 


e@ The screen type conversion is automatically handled by the 
PutBlk routine in the driver. 


@ GET/PUT buffers cannot be scaled. The image will be 
clipped if it does not fit within the window. 
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ScaleSw Scale Switch 


Function: Disables and enables automatic scaling. Normally, 
automatic scaling is enabled. When scaling is enabled, coordi- 
nates refer to a relative location in a window that is propor- 
tionate to the size of the window. When scaling is disabled, 
coordinates passed to a command will be the actual coordi- 
nates for that type of screen relative to the origin of the 
window. 


Code: 1B 35 


Parameters: BSW 


BSW = switch 
00 = off 
01 = on (Default) 


Notes: 


o e A useful application of disabled scaling is the arrangement 
of references between a figure and text. 


e All coordinates are relative to the window’s origin (0,0). 
The valid range for the coordinates: 


Scaling enabled: 


0-191 
0-639 


Scaling disabled: 


3 
x 


O-size of y - 1 
O-size of x - 1 


xy 
x 
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Select Window Select 


Function: Causes the current process’s window to become the 
active (display) window. You can select a different window by 
using the form: 


display 1B 21 >/wnumber 


where number is the desired window number. If the process 
that executes the select is running on the current interactive 
(input/display) window, the selected window becomes the 
interactive window, and the other window becomes passive. 


Code: 1B 21 


Parameters: None 


Notes: 
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The keyboard is attached to the process’s selected window 
through the use of the key. This lets you input data 
from the keyboard to different windows by using the 
key to select the window. 


All display windows that occupy the same screen are also 
displayed. 


The device window which owns the keyboard is the current 
interactive window. The interactive window is always the 
window being displayed. Only one process may receive 
input from the keyboard at a time. Many processes may be 
changing the output information on their own windows; 
however, you can only see the information that is displayed 
on the interactive window and any other window on the 
same screen as the interactive window. 


Eee 


General Commands / 3 


TCharSw Transparent Character Switch 


Function: Defines the character mode to be used when putting 
characters on the graphics screens. 


In the default mode (transparent off), the system uses block 
characters that draw the entire foreground and background for 
that cell. 


When in transparent mode, the only pixels that are changed 
are the ones where the character actually has pixels set in its 
font. When transparent mode is off, all pixels in the character 
block are set: foreground or font pixels in the foreground color 
and others in the background color. 


Code: 1B 3C 
Parameters: BSW 
BSW = switch 
00 = off (Default) 
OF Ob 
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Chapter 4 


Drawing Commands 


All drawing commands relate to an invisible point of reference 
on the screen called the draw pointer. Originally, the draw 
pointer is at position 0,0. You can change the position by using 
the SetDPtr and RSetDPtr commands described in this chapter. 
In addition, some draw commands automatically update the 
draw pointer. For example, the LineM command draws a line 
from the current draw pointer position to the specified end coor- 
dinates and moves the draw pointer to those end coordinates. 
The Line command draws a line but does not move the pointer. 


Also, note that all draw commands are affected by the pattern 
and logic commands described in Chapter 3. 


Do not confuse the draw pointer with the graphics cursor. The 
graphics cursor is the graphic representation of the mouse/joy- 
stick position on the screen. 


In this chapter, commands that use relative coordinates (offsets) 
are listed with their counterparts that use absolute coordinates. 
For example, RSetDPtr is listed under SetDPtr. 
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Arc3P Draw Arc 


Function: Draws an arc with its midpoint at the current draw 
pointer position. You specify the curve by both the X and Y 
dimensions, as you do an ellipse. In this way, you can draw 
either elliptical or circular arcs. The arc is clipped by a line 
defined by the (X01,Y01) - (X02,Y02) coordinates. These coor- 
dinates are signed 16 bit values and are relative to the center 
of the ellipse. The draw pointer remains in its original 
position. 


Code: 1B 52 


Parameters: HBRx LBRx HBRy LBRy HX01 LX01 HY0O1 
LY01 HX02 LX02 HY02 LY02 


Notes: 


@ The resulting arc depends on the order in which you specify 
the line coordinates. Arc3P first draws the line from Point 
1 to Point 2 and then draws the ellipse in a clockwise 
direction. 


@ The coordinates of the screen are as follows: 


-Y 


+¥Y 


Drawing Commands / 4 


Bar Draw Bar 


Function: Draws and fills a rectangle that is defined by the 
diagonal line from the current draw pointer position to the 
specified position. The box is drawn in the current foreground 
color. The draw pointer returns to its original location. 


Code: 1B 4A 
Parameters: HBX LBX HBY LBY 


RB AY Relative Draw Bar 


Function: Draws and fills a rectangle that is defined by the 
diagonal line from the current draw pointer position to the 
point specified by the offsets. The box is drawn in the current 
foreground color. The draw pointer returns to its original loca- 
tion. This is a relative command. 


Code: 1B 4B 
Parameters: HBXo LBXo HBYo LBYo 
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OS-9 Windowing System 


Box Draw Box 


Function: Draws a rectangle that is defined by the diagonal 
line from the current draw pointer position to the specified 
position. The box is drawn in the current foreground color. 
The draw pointer returns to its original location. 


Code: 1B 48 
Parameters: HBX LBX HBY LBY 


RBox Relative Draw Box 


Function: Draws a rectangle that is defined by the diagonal 
line from the current draw pointer position to the point speci- 
fied by the offsets. The box is drawn in the current foreground 
color. The draw pointer returns to its original location. This is 
a relative command. 


Code: 1B 49 
Parameters: HBXo LBXo HBYo LBYo 


404 
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Drawing Commands / 4 


Circle Draw Circle 


Function: Draws a circle of the specified radius with the cen- 
ter of the circle at the current draw pointer position. The cir- 
cle is drawn in the current foreground color. The draw pointer 
remains in its original location. 


Code: 1B 50 
Parameters: HBR LBR 
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Ellip S@€ Draw Ellipse 


Function: Draws an ellipse with its center at the current draw 
pointer position. The X value specifies the horizontal radius, 
and the Y value specifies the vertical radius. The ellipse is 
drawn in the current foreground color. The draw pointer 
remains in its original location. This is a relative command. 


Code: 1B 51 
Parameters: HBRx LBRx HBRy LBRy 
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FF ill Fiooa Fil 


Function: Fills the area where the background is the same 
color as the draw pointer. Filling starts at the current draw 
pointer position, using the current foreground color. The draw 
pointer returns to its original location. This is a relative 
command. 


Code: 1B 4F 


Parameters: None 
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Line Draw Line 


Function: Draws a line from the current draw pointer position 
to the specified point, using the current foreground color. The 
draw pointer returns to its original location. 


Code: 1B 44 
Parameters: HBX LBX HBY LBY 


RLine Relative Draw Line 


Function: Draws a line from the current draw pointer position 
to the point specified by the x,y offsets, using the current fore- 
ground color. The draw pointer returns to its original location. 
This is a relative command. 


Code: 1B 45 
Parameters: HBXo LBXo HBYo LBYo 
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LineM Draw Line and Move 


Function: Draws a line from the current draw pointer position 
to the specified point, using the current foreground color. The 
draw pointer stays at the new location. 


Code: 1B 46 
Parameters: HBX LBX HBY LBY 


RLineM Relative Draw Line and Move 


Function: Draws a line from the current draw pointer position 
to the point specified by the offsets, using the current fore- 
ground color. The draw pointer stays at the new location. This 
is a relative command. 


Code: 1B 47 
Parameters: HBXo LBXo HBYo LBYo 
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OS-9 Windowing System 


Point Draw Point 


Function: Draws a pixel at the specified coordinates, using 
the current foreground color. 


Code: 1B 42 
Parameters: HBX LBX HBY LBY 


RPoint Relative Draw Point 


Function: Draws a pixel at the location specified by the off- 
sets, using the current foreground color. This is a relative 
command. 


Code: 1B 43 
Parameters: HBXo LBXo HBYo LBYo 
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Drawing Commands / 4 


PutGC put Graphics Cursor 


Function: Puts and displays the graphics cursor at the speci- 
fied location. The coordinates passed to this command are not 
window-relative. The horizontal range is 0 to 639. The vertical 
range is 0 to 191. The default position is 0,0. 


This command is useful for applications running under GrfInt 
so that you can display a graphics cursor under WindInt even 
if you don’t want mouse control of the cursor. 


Code: 1B 4E 
Parameters: HBX LBX HBY LBY 
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OS-9 Windowing System 


SetDPtr Set Draw Pointer 


Function: Sets the draw pointer to the specified coordinates. 
The new draw pointer position is used as the beginning point 
in the next draw command if other coordinates are not 
specified. 


Code: 1B 40 
Parameters: HBX LBX HBY LBY 


RSetDP tY Relative Set Draw Pointer 


Function: Sets the draw pointer to the point specified by the 
offsets. The new draw pointer position is used as the begin- 
ning point in the next draw command if other coordinates are 
not specified. This is a relative command. 


Code: 1B 41 
Parameters: HBXo LBXo HBYo LBYo 
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Chapter 5 


Text Commands 


The text commands let you control the cursor’s position and 
movement and also the way text prints on the display. These 
commands can be used on either text or graphics windows. 


The text commands are: 


Code 


1F 20 
1F 21 
1F 22 
1F 23 
1F 24 


Description 
Homes the cursor. 


Positions cursor to x,y. Specify coordinates as 
(x + $20) and (y+ $20). 


Erases the current line. 


Erases from the current character to the end of 
the line. 


Turns off the cursor. 

Turns on the cursor. 

Moves the cursor right one character. 
Rings the bell. 

Moves the cursor left one character. 
Moves the cursor up one line. 

Moves the cursor down one line. 


Erases from the current character to the end of 
the screen. 


Erases the entire screen and homes the cursor. 
Sends a carriage return. 

Turns on reverse video. 

Turns off reverse video. 

Turns on underlining. 

Turns off underlining. 


Turns on blinking. 


OS-9 Windowing System 


Code 
1F 25 
1F 30 
1F 31 
1B 3C BSW 
1B 3D BSW 
1B 3F BSW 


Description 


Turns off blinking.’ 


Inserts a line at the current cursor position. 


Deletes the current line. 
See TCharSw in Chapter 3.” 
See BoldSw in Chapter 3.” 
See PropSw in Chapter 3.? 


1 Blink is not supported for text on graphics screens. 


2 These characteristics are supported for text on graphics 


screens only. 
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Index 


active window 3-34 buffers (cont'd) 
AND 3-21 screen type 3-32 
arc, draw 4-2 size 3-32 
ARC8P 4-2 save 3-18 
background color 3-2, 3-13 carriage return 5-1 
BAR 4-3 change font 3-15 
bar, draw 4-3 character 
bar, relative draw 4-3 erase 5-1 
BCOLOR 3-2 transparent 3-35 
bell, ring 5-1 CIRCLE 4-5 
blinking 5-1, 5-2 circle, draw 4-5 
off 5-2 close buffer 3-20 
on 5-1 close overlay window 3-23 
boldface 3-3, 5-2 close, window 3-10, 3-23 
BOLDSW _ 3-3, 5-2 color 3-26 
BORDER _ 3-4, 3-26 background 3-2, 3-13 
border color 3-4, 3-13, 3-26 border 3-4, 3-13, 3-26 
BOX 4-4 composite 3-27 
box, draw 4-4 default 3-6 
box, relative draw 4-4 foreground 3-13, 3-14, 
buffer, kill 3-20 | 3-26 
buffer, load 3-19 graphics 3-6 
buffers 3-7, 3-19 high-resolution 3-6 
buffers palette 3-26 
close 3-20 RGB 3-26 
define 3-7 VDG-emulation 3-6 
font 3-19 command parameters 2-1 
get/put 3-19 commands 
get/put 38-7 drawing 2-1, 4-1 
patterns 3-29 general 2-1, 3-1 
save 3-18 text 2-1, 5-1 
group numbers 3-7 composite colors 3-27 
kill 3-20 create windows 
load 3-19 device 1-2 
logic 3-21 overlay 1-4 
pattern 3-29 current window 3-13, 3-34 
16-color 3-31 cursor 3-17 
2-color 3-30 home 5-1 
4-color 3-31 graphics 3-17 
pattern array 3-29 put 4-11 
pattern size 3-29 move 5-1 
put 3-32 off 5-1 
block 3-32 on 5-1 
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cursor (cont’d) 
position 5-1 
set 3-17 

CWAREA 3-5 


default color 3-6 
default windows 1-3 
DEFCOLR 3-6 
define buffers 3-7 
define device windows 3-12 
delete line 5-2 
device descriptors 1-1, 3-12 
device windows 1-1 
background color 3-13 
border color 3-13 
color 
background 3-13 
border 3-13 
foreground 3-13 
define 3-12 
end 3-10 
foreground color 3-13 
keyboard 3-34 
location 3-13 
process window 3-13 
protect 3-11 
select 3-34 
set 3-12 
DFNGPBUF 3-7 
DISPLAY 1-2, 2-1, 3-12 
draw pointer 4-1 
relative set 4-12 
set 4-12 
draw 
arc 4-2 
bar 4-3 
bar, relative 4-3 
box 4-4 
box, relative 4-4 
circle 4-5 
ellipse 4-6 
fill 4-7 
flood fill 4-7 
line 4-8 
line and move 4-9 


draw (cont'd) 
line and move, 
relative 4-9 
line, relative 4-8 
point 4-10 
point, relative 4-10 
pointer 4-1 
drawing commands 4-1 
DWEND 3-10 
DWPROTSW_ 3-11 
DWSET 1-1, 1-2, 3-12 


ELLIPSE 4-6 

ellipse, draw 4-6 

end overlay window 3-23 
end window 3-10, 3-23 
erase character 5-1 

erase line 65-1, 5-2 

erase screen 5-1 

erase to end of screen 5-1 
escape sequence 1-2 


FCOLOR 3-14 

FFILL 4-7 

fill, draw 4-7 

flood fill, draw 4-7 

FONT 3-15 

font 3-12, 3-15, 3-19 
bit map 3-15 
boldface 3-3, 5-2 
change 3-15 
current 3-15 
data 3-15 
load 3-19 
order 3-15 


proportional 3-15, 3-28, 


5-2 
font bit map 3-15 
font data 3-15 
font load 3-19 
font order 3-15 
foreground color 3-13, 3-14, 
3-26 


GCSET 3-17 


oo 


general commands 2-1, 3-1 
get/put buffers 
close 3-20 
define 3-7 
font 3-19 
group numbers 3-7 
kill 3-20 
load 3-19 
logic 3-21 
patterns 3-29 
put 3-32 
save 3-18 
GETBLK 3-18 
GPLOAD _ 3-9, 3-15, 3-19, 3- 
32 
graphic patterns 3-29 
graphics 
boldface 3-3 
colors 3-6 
cursor 3-17, 4-11 
put 4-11 
set 3-17 
font, proportional 3-28 
transparent 3-35 
group numbers 3-7, 3-8 
Grp__Clip 3-8 
Grp_Fnt 3-8 
Grp.Pat2 3-8 
Grp__Pat4 3-8 
Grp__Pat6 3-8 
Grp_Ptr 3-8 


high-resolution, colors 3-6 
home cursor 5-1 


I$ ATTACH 3-10 
immortal shell 1-3 
INIZ 1-2, 3-10, 3-12 
insert line 5-2 
interactive window 3-34 


KILBUF 3-20 
kill buffer 3-20 


Index 


LINE 4-8 
line 
delete 5-2 
draw 4-8 
erase 5-1, 5-2 
insert 5-2 
relative draw 4-8 
line and move, draw 4-9 
line and move, relative draw 
4-9 
LINEM 4-1, 4-9 
load get/put 3-19 
load font 3-15, 3-19 
location, window 3-13 
logic operations 3-21, 4-1 
logic set 3-21 
LSET 3-21 


memory 1-1, 3-12 
MONTYPE 3-6 
move cursor 5-l 


open windows 


device 1-2 
overlay 1-4 
OR 3-21 


overlay window 1-1, 1-2, 3-23, 
3-24 

overlay window 
end 3-23 
no-save 3-24 
save 3-24 
select 3-34 
set 3-24 
size 3-24 
stacked 3-25 

OWEND 3-23 

OWSET 1-4, 3-24 


PALETTE 3-26 

palette colors 3-26 

parameters, command 2-1 

pattern 3-29, 4-1 
16-color 3-31 
2-color 3-30 
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pattern (cont'd) 
4-color 3-31 
array 3-29 
size 3-29 
POINT 4-10 
point, draw 4-10 
point, relative draw 4-10 
pointer, draw 4-1 
position cursor 95-1 
process window 3-13 
proportional characters 3-28, 
proportional font 3-28 
PROPSW _ 3-28, 5-2 
protect device windows 
PSET 3-29 
put block 3-32 
put buffer 3-32 
screen type 3-32 
size 3-32 
put graphics cursor 4-11 
PUTBLK 3-18, 3-19, 3-32 
PUTGC 4-11 


3-11 


RBAR 4-3 

RBOX 4-4 

reverse video 5-1 
RGB colors 3-26 
ring bell 5-1 

RLINE 4-8 
RLINEM 4-9 
RPOINT 4-10 
RSETDPTR 4-1, 4-12 


save, get/put 3-18 

save window 3-18 
SCALESW 3-33 
scaling 3-33 

scaling, automatic 3-33 
scaling coordinates 3-33 
screen type 3-12 
screen, erase 5-1 
SELECT 3-34 

select window 3-34 


set 
device window 3-12 
draw pointer 4-12 
draw pointer, relative 
4-12 
overlay window 3-24 
SETDPTR 4-1, 4-12 
SETSTAT 3-6 
SHELL 1-3 
shell, fork 1-3 
stacked overlay windows 3-25 


TCHARSW _ 3-35, 5-2 
text commands 5-1 
text 
boldface 3-3, 5-2 
proportional 3-28, 5-2 
transparent character 3-35, 
5-2 


underline 
off 5-1 
on 5-1 


video, reverse 5-1 


WCREATE 1-2 
windows 1-l 
background color 3-2, 
3-13 
boldface 3-3, 5-2 
border color 3-4, 3-13, 
3-26 
buffers 3-7, 3-19 
kill 3-20 
load 3-19 
patterns 3-29 
put 3-32 
close 3-10, 3-23 
color 3-26 
background 3-2, 
3-13 
border 3-4, 3-13, 
3-26 
composite 3-27 


windows (cont'd) 


default 3-6 
foreground 3-18, 
3-14, 3-26 
RGB 3-26 
current 3-13 
cursor 3-17 
default 1-3 
default color 3-6 
device 1-l 
define 3-12 
end 3-10 
opening 1-2 
protect 3-11 
select 3-34 
set 3-12 


device descriptors 1-1, 


3-12 
end 3-10 
fonts 3-15, 3-19 
foreground color 3-13, 
3-14, 3-26 
graphics cursor 3-17, 
4-11 
interactive 3-34 
keyboard 3-34 
location 3-13 
logic operations 3-21 
maximum 1-1 


Index 


windows (cont'd) 


memory 1-1, 3-12 
overlay 1-1, 1-2, 3-23, 
3-24 
end 3-23 
no-save 3-24 
opening 1-4 
save 3-24 
select 3-34 
set 3-24 
size 3-24 
stacked 3-25 
process window 3-13 
process 3-13 
protect 3-11 
put buffer 3-32 
save 3-18 
scaling 3-33 
screen type 3-12 
select 3-34 
size 3-5 
transparent mode 3-35, 
5-2 
type 1-1 
work area 3-5 


work area 3-5 


XOR 3-21 
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active processes. Operations that the system is currently 
executing. 


active state. An operating or working condition. A procedure 
in an active state is processing data and not waiting for another 
procedure to end. 


address. A number that identifies a location in your comput- 
er’s memory. 


age. A count of the number of switches (process changes) the 
system has made since a process’s last time slice. 


anonymous directory. A directory referenced by its hierarchi- 
cal position using the period (.) character. One period refers to 
the current directory. Two periods refer to the parent of the cur- 
rent directory, and so on. 


application program. A process or group of processes 
designed to accomplish specific tasks, such as word processing, 
data management, game playing, and so on. 


argument. Data you supply to a process or command for it to 
evaluate. 


array. Data arranged so that each item is located by its row 
and column position. Single-dimensioned arrays have one or more 
rows and one column. Multi-dimensioned arrays have one or 
more rows and two or more columns. 


ASCII code. American Standard Code for Information Inter- 
change. A method of defining alphabetic and numeric characters 
and other symbols by giving each a unique value. For instance, 
the ASCII value for A is 65, and the ASCII value for B is 66. 


assembler. A program that produces machine code from source 
code (code from a low-level computer language). 


assembly language. A system for coding computer instruc- 
tions to perform tasks. You can use assembly language code to 
directly manipulate data within a computer; therefore, assembly 
language needs less interpretation than higher level languages 
like BASIC or Pascal. 


attribute. See file attribute. 
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background processing. Executing one or more procedures 
and at the same time continuing to operate in OS-9 or in 
another procedure. 


backup. An identical copy of the contents of one disk on 
another disk. 


base. The lowest value allowed in a function or operation. For 
instance, BASICO9 allows a base value of 1 for array structures 
unless you indicate otherwise. 


batch file. See procedure file. 


baud. Bits-per-second. A unit for measuring the speed of data 
flow between devices. 


binary. A numbering system using only two digits, 0 and 1. In 
this system, shifting the position of a digit to the left raises the 
value of the digit by the power of 2. For instance, 1 is the binary 
equivalent of 1,10 = 2, 100 = 4, 1000 = 16, and so on. 


bit. The smallest unit of a computer’s memory. Eight bits form 
a byte. Each bit can have a value of either 0 or 1. 


bit map. A storage area of 256 bytes. Each bit represents one 
page (256 bytes) of your computer’s memory. If a bit is set 
(equals 1) then its associated memory page is allocated. If a bit 
is reset (equals 0) then its associated memory page is free. 


block. A group of data, often comprising 256 bytes. 


block-oriented device. A device that receives data, sends 
data, or both, in groups of 256 bytes. 


Boolean logic. A binary type of algebra developed by George 
Boole. 


Boolean data type. A type of variable that can have only two 
values, True or False. Boolean data types usually store the 
results of comparisons, such as: is A greater than B (A>B), does 
Y equal X (Y=X), and so on. 


boot. The process of loading and initializing OS-9. 


bootfile. A disk file containing modules to be loaded during an 
OS-9 boot. 


bootlist. A disk file containing a list of module names to be 
used by OS9Gen to create a bootfile. 
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bootstrap module. A program that contains the code neces- 
sary to initialize OS-9. 


border. An area around a screen or window that defines the 
boundaries of the screen or window. 


branch. To leave one routine and begin execution of another 
routine within a program or procedure. 


breakpoints. Locations in a program or procedure at which 
you want execution to pause. 


buffer. A temporary storage area through which OS-9 trans- 
fers data. 


byte. A unit of computer memory storage that contains a value 
in the range 0-255. 


byte data type. A numeric type of variable that can contain 
unsigned eight-bit integer data (in the range 0-255 decimal). 


call. (1) To transfer execution to another routine, then return 
to the calling procedure with obtained values intact and avail- 
able for use by the calling routine. (2) A built-in OS-9 routine 
that performs a system function. 


CC3Disk. The floppy diskette driver module. 
CC3I0O. The system input/output driver. 


chaining. A process of calling and turning over system control 
to a new procedure. 


checksum. A value calculated from the contents of a file or 
module that the system can later use to verify whether the con- 
tents of the file or module are uncorrupted. 


child or child process. A process begun from another (par- 
ent) process. 


close. The process of deallocating the path to a device or file. 


cluster. A group of sectors. In OS-9 for the Color Computer, a 
cluster consists of only one sector. 


code. Numeric data that can be used by a computer to perform 
a task. 


command. The name of an OS-9 program or function. 
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command line. One or more commands with all their parame- 
ters, options, and modifiers. 


command modifiers. Data or values appended to a command 
that change the way the command functions. 


command options. Data that you can include in a command 
line to specify the way the command functions. 


command parameters. Data or values appended to a com- 
mand that define or customize the command. 


command separator. A semicolon. You can use a semicolon to 
separate several commands on the same command line. 


compile. To create machine language code (object code) from a 
program written with a computer language. Also to translate 
high level code (from a high level language such as BASIC) into 
low level code (code that is like machine language). 


complement. A value that is derived by subtracting a number 
from a constant. For example, the 10s complement of 4 is 6. In 
binary, a value is complemented by changing all the 1 digits to 0 
and all the 0 digits to 1, then adding 1 to the least significant 
(rightmost) digit. 


complex data structure. A group of data that contains two or 
more types of data structures. See data structure. 


constant. A value or block of data that is fixed (does not 
change during the run of a program or procedure). 


CPU. Central Processing Unit. An integrated circuit (chip) 
that controls the operation of a computer. 


current directory. The directory in which OS-9 looks for data 
files or stores data files unless you specify otherwise. 


current line. When editing, the line on which the editing cur- 
sor or pointer is located. 


cursor (text). A colored box that shows where the next charac- 
ter is to appear on the screen. A text cursor appears on both text 
and graphics windows or screens. 


cyclic redundancy check (CRC). A value the system calcu- 
lates from the data stored in a module. The system calculates a 
new value each time it attempts to load the module. If the calcu- 
lated value does not match the CRC value contained in the mod- 
ule, the system cannot load the module. 
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cylinder. A disk track that includes both sides of a disk. See 
also track. 


DAT. Dynamic address translation. The memory management 
system used by OS-9 Level Two. 


data directory. The directory in which OS-9 automatically 
saves files unless you specify otherwise. 


data structure. A unit of data, organized for access. 


data type. A method for representing data, such as character 
(ASCII value), integer (whole number), or real (floating point 
number). 


deadlock. See deadly embrace. 


deadly embrace. A situation in which two processes attempt 
to gain control of the same disk areas at the same time. 


debug. To find and correct program errors. 


decompile. To translate machine language code into a com- 
puter language code. 


delimiter. A character that divides items. For instance, in 
OS-9, the semicolon is a delimiter that divides two commands on 
the same line. 


descriptor. See device descriptors. 


device. A data source, destination, or both. OS-9 devices can 
exist in your computer’s memory (such as a window or a RAM 
disk), or they can be external equipment (such as a printer or 


disk drive). 


device descriptors. Small tables that define a device, its 
name, its driver, and its file manager. Device descriptors also 
contain port initialization data and port address information. 


device drivers. Modules that handle basic input/output func- 
tions for specific devices. Each device you use with your computer 
must have its own driver to interpret the code you send it. 


device name. A unique system word for a device. The name for 
disk Drive 0 is /DO, the name for Window 1 is /W1, and so on. 


device table. See device descriptor. 
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device window. An OS-9 device from which you can run a 
program or utility. Access device windows in the same manner 
as you do other devices. Each device window has its own input 
and output buffers. Refer to windows using device names (/W fol- 
lowed by a number), such as /W1, /W2, /W8, and so on. 


directory. A file in which OS-9 stores a list of other files, 
including their names, locations on the disk, attributes, and so 
on. 


disk allocation map. Logical Sector Number 1 on a disk. The 
data in LSN1 indicates which sectors are allocated to files and 
which sectors are free. 


double click. To press and release the mouse button twice in 
quick succession when the pointer is over the desired location. 


drag. To hold down the mouse button and move the mouse to a 
new position before releasing the button. 


draw pointer. An indicator that determines where the next 
graphics draw command will begin unless you specify otherwise. 


driver. See device driver. 


dump. To write the contents of a video screen, a memory loca- 
tion or a file to another terminal, memory location, or file. 


echo. To cause data being sent to one device to go to another 
device, as well. 


edit. To change the data or values in a file or in your comput- 
er’s memory. 


edit buffer. An alternate workspace for the OS-9 Macro 
Editor. 


edit macro. A series of commands you can execute with only a 
single command. 


edit pointer. An indicator that determines where the next edit 
command is to operate unless you specify otherwise. 


editor. A program that provides special commands to aid you 
in changing the contents of a file. 


error code. A code that OS-9 displays when it cannot under- 
stand what you want it to do or when your computer or a periph- 
eral malfunctions. Use the displayed code number to look up a 
description of the error. 
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error path. The route through which OS-9 sends error codes 
and other information to display on the screen. The error path is 
designated as Path Number 2. 


error trap. A routine in a procedure that checks for an error 
and provides an alternate action (other than terminating execu- 
tion and displaying a system error message). 


executable file. A program file that you can run by typing 
and entering its filename. 


execute. To start a procedure, program, or command (cause it 
to run). 


execution directory. The disk directory that contains your 
system’s command files. 


execution modifiers. See command modifiers. 


execution offset. The location in a program or subroutine at 
which execution begins, calculated from the beginning of the 
module. 


expressions. Data items joined by arithmetic operators. See 
also operator. 


expression stack. A memory location in which BASICO9 
stores temporary results while it evaluates an expression. 


file. (1) A block of information your computer uses for a partic- 
ular function or program. A file can contain an operating sys- 
tem, a language, an application program, or text. (2) A collection 
of associated records, such as information about each book in a 
library. 


file attribute. Data that identifies a file, for instance its size, 
security status, language type, and so on. 


file locking. Protecting a file to ensure that one process does 
not change it while another process is using it. 


file pointer. An indicator that determines where in a file the 
next read or write operation is to occur unless you or the system 
indicates otherwise. 


file security. A set of attributes that determines who can use 
a file and in what manner. 


filename. A set of characters that uniquely identifies and 
locates a block of data stored on a disk. 
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filter. To alter data in some manner as it passes between two 
devices or between two memory locations. 


flag. A symbol or value that indicates when a certain condition 
exists in a procedure. 


font. A character set. A group of alphabetic and numeric char- 
acters and other symbols of a particular style and shape. 


foreground. (1) An OS-9 task that takes priority over other 
concurrently running tasks. (2) Characters or designs on a 
screen or window. 


fork. The process of initializing one procedure from another 
procedure. 


format. To magnetically organize a diskette so that the com- 
puter can use it to store data. 


function. In BASICO9, an operation that BASIC performs on 
data. A function always returns (produces) a value of some type. 


Get/Put buffer. A buffer in which you or the system can store 
fonts, screen patterns, graphic displays, overlay windows, and 
other recallable data. The system allocates Get/Put buffers in 8- 
kilobyte blocks. 


getstat. An OS-9 routine that gets (returns) the state or status 
of a specific system operation. 


global variable. A variable that is available to all procedures 
and routines in a program. 


graphics. An arrangement of elements (lines, dots, and so on) 
on your computer’s screen. 


graphics cursor. An indicator (either visible or invisible) that 
determines where the next graphic function is to occur on the 
screen unless you or a program specifies otherwise. In applica- 
tions, you often move the graphics cursor using a mouse. 


graphics pointer. See graphics cursor. 


graphics screen. A screen in which all pixels are represented 
by bits in a memory map. You create images on the screen by 
manipulating the bits using special OS-9 or computer language 
commands. 
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graphics window. A window created on a graphics screen. 
You can display both graphics (drawn images) and text on a 
graphics window. The text generated on a graphics window/ 
screen uses software fonts that you or the system must load into 
memory. 


group. An organization of related data or files. For instance, 
OS-9’s graphics buffers are organized into groups that you refer- 
ence by number. 


hardware. The physical parts of your computer, including its 
disk drives, keyboard, integrated circuits (chips), and so on. 


header. Data located at the beginning of a file or module to 
identify its type, size, verification values, and so on. 


hexadecimal. A number system to a base of 16 (using 16 dig- 
its). Hexadecimal digits are 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, 
E, and F. Shifting a hexadecimal digit one place to the left 
causes its value to be multiplied by 16. 


high order bit. The most significant or leftmost bit in a byte. 
If the high order bit is 0, it represents a value of 0. If the high 
order bit is 1, it represents a value of 128. 


T/O. Input/Output. 


identification sector. Logical Sector Number 0 on a disk. 
LSNO contains a description of the physical and logical organiza- 
tion of a disk. 


immortal shell. An OS-9 shell that does not die on receiving 
an EOF signal (such as when you press (CTRL ]{ BREAK }). 


integer data type. A type of variable that can store whole 
numbers in the range -32768 to 32767. 


interactive window. A window that is getting input from the 
keyboard. This window is currently on the displayed screen. 


interface. To link devices or modules together in order to 
transfer data. 


internal integrity check. A system of internal values that 
OS-9 can use to make certain that its system modules and func- 
tions are accurate. 


IOMAN. The input/output manager that provides common pro- 
cessing for all input/output operations. 
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IRQ. Interrupt request. A signal that causes the execution of 
one process to halt and the execution of another process to begin. 
The system retains the values of the first process so that it can 
later continue its execution. 


kernel. OS-9 software that supervises the OS-9 system and 
provides basic system services, such as multitasking and memory 
management, and that links all system modules. 


key sequence. Two or more keys you press at the same time to 
produce a specific function. 


keyboard mouse. An OS-9 function that lets you use the key- 
board arrow keys instead of an external mouse device. Press 


to toggle the keyboard mouse on and off. 
keyword. A command name. 

kill. Terminate the execution of a process. 
kilobyte. 1024 bytes. 

link. To make a module available to a process. 


link count. The number of processes using a module. When a 
module’s link count reaches 0, OS-9 deallocates the module. 


load. To transfer data from an external device into your com- 
puter’s memory. 


local variable. A variable that can be used by only the proce- 
dure or routine in which it resides. 


locked. See file locking. 
lockout. See file locking. 


log in. To initiate the necessary procedure to operate OS-9 
from a separate terminal (type in a user name and password). 


logical address. An offset address. An address that is num- 
bered from the beginning of a block rather than from the begin- 
ning of memory, a module, or other storage area. 


logical sectors. Sectors that OS-9 or a program references in 
numeric order, regardless of their actual physical location on a 
disk. 


loop. A sequence of BASICO9 commands that execute repeat- 
edly a specified number of times or until a specific condition 
occurs to terminate the execution. 
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macro. A series of commands you can execute with only a sin- 
gle command name. 


map. See memory map. 


mask. A pattern of bits that you use in combination with a 
logical operator to change specified data selectively — reversing 
certain bits without affecting the others. 


megabyte. One million bytes. 


memory. The portion of your computer that stores data and 
values. 


memory management. Assigning and mapping memory to 
keep track of modules (processes and data) and their uses. 


memory map. A chart depicting the use of your computer’s 
memory by the operating system. 


menu. A screen display from which you select an action for 
your computer. 


microprocessor. An integrated circuit (chip) that controls the 
basic operation of your computer. 


mode. A particular function of a program or system. 


modem. Modulator/demodulator. A device to prepare signals 
for transmission through telephone lines and to reverse the pro- 
cess after transmission. 


modifier. See command modifier. 


module. An OS-9 program or block of data residing in your 
computer’s memory. 


module body. A module’s code (program or data), including 
the module name. 


module directory. A table in your computer’s memory that 
lists all the modules residing in memory. 


module header. Code that resides at the beginning of all mod- 
ules and that contains information about the module, including 
size, type, attributes, storage requirements, and its execution 
starting address. 


monitor. The video display device connected to your computer. 
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mouse. A device you use to control a pointer on the display 
screen. In application programs, you can often use a mouse to 
indicate functions you want to initiate. 


multi-programming. A method of computer operation in 
which the system allocates slices of execution time to more than 
one process in order to execute them concurrently. 


multi-tasking. Executing more than one process at the same 
time. 


multi-user. A system that lets more than one person access its 
functions at the same time. 


nesting. Incorporating one structure into another structure of 
the same type. Both procedures then retain their individual 
identities. 


non-shareable file. A file or module that can be used by only 
one procedure or user at one time. 


null string. A string variable that does not contain a value 
(has a length of 0 characters). 


object code. Machine language instructions. 


offset. The difference between a location and a beginning loca- 
tion. For instance, you can tell some BASICO9 graphics functions 
to begin operation at a location that is offset from the current 
draw pointer position. 


operand. A value that is used or manipulated during an oper- 
ation or during the execution of an instruction. 


operating system. A set of associated programs that carry 
out your commands. 


operator. A symbol or word that signifies some action to be 
performed on specified data. 


options. See command options. 


output path. The route through which the system sends data 
from one device to another. 


overflow. A condition in which a storage space is not large 
enough to contain the data sent to it. 


overlay. A condition in which programs or modules in a com- 
puter’s memory are replaced with other data. 
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overlay window. A window opened or placed on top of a device 
window. 


overwrite. To replace data with other data. 


owner. An entity that has control over a file, module, or 
process. 


pack. To compile a BASICO9 procedure. See compile. 


padding. Adding spaces to a string or unit of data to make it 
a specific length. 


page. In your computer’s memory, a block of 256 bytes. 
paint. To fill all or a portion of the screen with a color. 


palette. A register that contains a numeric code representing a 
color or shade. 


parameters. See command parameters. 


parent or parent process. A process that forks (starts) 
another process (a child process). 


parity. A system in which all binary numbers of a code are 
converted to either even-bit numbers (an even number of 1s) or 
odd-bit numbers (an odd number of 1s). 


parse. To search through a list or sequence of data. 
Pascal. A high-level computer language. 


pass by value. When BASICO9 passes a value from one proce- 
dure to another by evaluating a constant or expression and plac- 
ing the result in temporary storage to be accessed by the second 
procedure. 


pass by reference. When BASICO9 passes a variable from one 
procedure to another by providing the second procedure with the 
address of the variable’s storage. 


passive window. Any window that is not receiving input from 
the keyboard. A process can be running on a passive window 
provided that the process is getting its input from a source other 
than the keyboard. 
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pathlist. The route from one position in a disk’s directory to 
another directory or file. 


peripherals. Devices connected to your computer, such as 
printers, disk drives, and so on. 


permission. The attributes of a file or module that determine 
who can use the file or module and in what manner. 


physical sectors. The actual arrangement of sectors on a 
disk’s surface, regardless of any internal organization by OS-9. 


pipe. A function in which the output of one process becomes 
the input of another process. 


pipeline. A series of commands, each of which passes the 
results of its operations to the next command in the series. 


PIPEMAN. The pipe file manager. Pipes are memory buffers 
acting as files to transfer data between processes. 


pixel. The smallest area of a display screen that can be manip- 
ulated (turned off or on). 


pointer. An indicator that determines a location in memory, in 
a file, or on the screen. 


port. A junction between devices through which data flows. An 
electrical connection between your computer and a peripheral. 


position independent module. A module that need not be 
loaded at any certain location in memory. 


procedure. A program or routine your computer can execute. 


procedure file. A file containing one or more OS-9 commands. 
You can execute a procedure file in the same manner as you exe- 
cute OS-9 commands or programs. 


process. A computer program or a routine that performs a 
specific task as part of a computer program. 


process descriptor. A block of data that includes information 
about a process, its state, memory allocations, priority, queue 
pointers, and so on. 


process ID. A unique number the system gives each process it 
executes. 
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process priority. A value you or the system gives to a process 
that determines the amount of CPU (execution) time it is to 
receive in a multi-tasking environment. 


process state. The condition of a process in regard to its exe- 
cution. A process can be active (executing), waiting (awaiting its 
turn for processing), or sleeping (inactive until it receives a sig- 
nal to awaken). 


program. Code that causes your computer to perform some 
function or a series of functions. 


program modules. Executable code. Modules you can run to 
perform a function or series of functions. 


public. Any user of a program or module other than the owner. 
See owner. 


purge. Delete. Usually refers to removing all, or a selected 
group, of files from a directory. 


RAM. Random access memory. Computer memory you can 
write to (change) and read from. 


RAM disk. A portion of your computer’s memory that OS-9 
can use for data storage and retrieval in the same manner as it 
uses an external disk drive. However, be certain you copy RAM 
disk data to a floppy diskette or hard disk before you exit OS-9 
or turn off your computer. If you do not, the data is lost. 


random access. Reading (accessing) information in a block of 
data without first having to read any preceding data. 


raw data. Unformatted information that is passed to a device 
exactly as it exists. 


RBF. The random block file manager that processes all disk 
input/output. 


re-entrant programs. Programs or modules that can be used 
by more than one process at the same time. 


read. The process of transferring data from a device into the 
computer’s memory. 


read permission. System permission to read (withdraw data 
from) a file. 
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real data type. A type of variable that can store floating point 
numbers in the range +1 x 10** 


record. A collection of related data items that a program or 
process considers to be a unit for the purpose of processing. A 
subdivision of a file, such as all information about a single item 
in an inventory file. 


record locking. Protecting a portion of a file to ensure that 
one process does not change it while another process is using it. 


recursive procedure or routine. A procedure or routine that 
repeatedly executes itself (that contains a statement causing it 
to run itself one or more times). 


register. A location within a computer’s memory (often in the 
CPU) for storing values during arithmetic, logic, or transfer 
operations. 


remarks. Text contained in a program that describes the pro- 
gram itself and that is not to be executed. 


ROM. Read only memory. Computer memory containing con- 
stant values that the computer can read but cannot change. 


ROOT directory. The parent directory of all files and directo- 
ries on a disk. The ROOT directory is created by FORMAT. 


run. To execute, or to cause a program or procedure to start. 
runtime. The duration of a program’s execution. 


SCF. The sequential character file manager that handles non- 
disk input/output operations to devices such as printers and 
terminals. 


scratched. Destroyed. When you copy one file over another file, 
or the contents of one disk onto another disk, any data existing 
in the second file or on the second disk is scratched. 


sector. A division of a disk track. Disk tracks are organized 
into several sectors. 


seek. To position a file pointer at a specific byte location in a 
file. 


semigraphics. Graphics (designs on the display screen) using 
ASCII graphic characters. 
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sequential access. The process of reading data in order, one 
character at a time. 


sequential execution. Executing a series of commands or pro- 
cesses, one after the other. 


sequential file. A file consisting of records of various lengths 
that must be accessed one after the other, starting at the first 
record. 


serial. Refers to transmissions in which data leaves or arrives 
at a location or device, with data units following one after the 
other in space or time. 


Setstat. An OS-9 routine that sets (changes) the state or sta- 
tus of a specific system operation. 


shell. The command interpreter. 


sibling. One of two or more processes executed by the same 
parent process. 


sign bit. The leftmost bit of a binary number that serves as an 
indicator to show whether the number is positive or negative. 
Normally, a value of 0 indicates positive, and a 1 indicates 
negative. 


signal. An interrupt from the system or another process that 
changes a procedure’s or a device’s state. For example, signals 
set an active process to a waiting state, awaken an inactive or 
sleeping process, or change the display window. 


single step. A procedure in the Debug mode that lets you exe- 
cute one procedure statement and (optionally) view the results. 


single-user file. A file that only one person can access at a 
time. 


single-user module. A program that only one person can use 
at a time. 


sleeping state. A situation where you or the system suspends 
a process for a specified time or until you or the system sends it 
a wakeup signal. 


source code. Program code produced using a computer lan- 
guage. Before it can control a computer, source code must be 
translated into machine language, either by a compiler or a 
translator program. See also compiler. 
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stack. A storage area in your computer's memory in which 
data can be placed or recovered in sequence, from one end only. 


standard error path. The route through which your computer 
sends error codes and other messages to the screen. 


standard input path. The route through which you can send 
data to your computer (usually the keyboard). 


standard output path. The route your computer uses to send 
data to the screen. 


start up. To turn on your computer and initialize OS-9. 


stop bits. One or two bits that a terminal program sends after 
each unit of data to indicate that the transmission of the unit is 
complete. 


string. A group of alphanumeric characters. 


string data type. A type of variable that can contain one or 
more ASCII values (values representing alphanumeric characters 
or other symbols). String data types can be any length, up to the 
capacity of your computer’s memory. 


structured programming. Building a program out of a series 
of procedures, each of which performs a specific task but com- 
bines with its associated procedures as one program. 


subdirectory. A directory that resides within another (parent) 
directory. 


subroutine. An operation that performs a specific task as part 
of a larger operation. 


super user. The system user who has control of the entire sys- 
tem and access to all system files and modules. User Number 0. 


symbolic debugging. An error correcting system that lets you 
pause program execution and view the current values of vari- 
ables, using their program names. 


syntax. The rules for forming legal instructions for your 
computer. 


system. (1) A group of files and programs that provide you 
with control over your computer. (2) Your computer with all its 
attached devices. 
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system call. Built-in OS-9 routines that perform particular 
functions, such as accessing disk files, printing data on the 
screen, and so on. 


table. A storage area in memory or on disk containing ordered 
data to be used by a process or function. 


task. A unit of work performed by your computer. 


terminal. A computer or an electronic device, with a screen 
and keyboard, connected to your Color Computer 3. You can 
access OS-9 functions from a terminal in the same manner as 
you can access them from your Color Computer 3 keyboard. 


text files. Files containing printable characters, or the code 
representing such characters. 


text screen. A Type 1 or 2 screen. Text screens use hardware 
generation of characters (fonts are not definable) and are often 
referred to as hardware screens or windows. Text screens cannot 
display graphics. Text operations occur faster in text windows/ 
screens than on graphic windows/screens. 


text window. Any window created on a hardware text screen. 


time slice. The period of time between system clock ticks. A 
tick occurs every 1/60th of a second. 


timesharing. A situation in which more than one person uses 
the same operating system. 


token. In the BASIC language, a numeric value that represents 
a keyword. 


trace. To display each procedure statement as it executes and 
view its results. 


tracks. Magnetically created concentric circles created on a 
disk for the storage of data. Tracks are established when you for- 
mat a disk. 


transparent characters. Characters that display over screen 
images without erasing any of the area surrounding the 
characters. 


unlink. To remove a module (program) from your computer’s 
memory. 


update mode. The condition of a file when it is open for both 
reading and writing. 
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OS-9 Glossary 


user ID. A number that identifies the operator to which a pro- 
cess belongs. 


user number. See user ID. 


utility. A short program that performs a frequently required 
task, usually for the maintenance of your computer system or 
files. 


variable. A unit of storage with no fixed value. You define a 
variable and locate it in your computer’s memory using a vari- 
able name. 


VDG. Video Display Graphics. 
vector. A graphics line or portion of a line. 
verify. To check data for accuracy. 


wait state. A situation in which a process remains suspended 
until one of its child processes terminates or until it receives a 
wakeup signal from the system. 


wake up. To continue the execution of a process that has been 
suspended. 


wild card. A symbol that represents or takes the place of one 
or more other characters or symbols. 


WINDINT. Window interface. 


window. All or a portion of your video screen with specific for- 
mats (columns, lines, size, colors, and so on) and type (graphics, 
text, or both). An area of a screen in which you can run a pro- 
cess or which can receive input. 


word length. The number of bits to transmit as one unit. 


workspace. A portion of your computer’s memory that 
BASICO09 establishes for the storage and manipulation of 
procedures. 


write. To transfer data from the computer’s memory to a 
device. 


write permit. System permission to change the data in a file. 


write protect. A method of protecting a diskette so that your 
computer cannot change the data on it. 
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